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COMPUTERIZED SYSTEM AND ASSOCIATED METHOD 
FOR OPTIMALLY CONTROLLING STORAGE AND TRANSFER 
OF COMPUTER PROGRAMS ON A COMPUTER NETWORK 

Rarkground of the Invention 

5 This invention relates to computing and communications on a computer network. 

More specifically, this invention relates to a computerized system and an associated method for 

optimally controlling storage and transfer of computer programs between computers on a 

network to facilitate interactive program usage. 

In the past several years, there has been an ever increasing number of individuals, 

10 corporations and other legal entities which have obtained access to the global network of 

computers known as the Internet. More precisely described, the Internet is a network of 

regional computer networks scattered throughout the worid. On any given day, the Internet 

connects roughly 20' million users in over 50 countries. That number will continue to increase 

annually for the foreseeable future. 

] 5 The Internet has provided a means for enabling individual access to enormous amounts 

of information in several forms including text, video, graphics and sound. This multi-media 

agglomeration or abstract space of information is generally referred to as the "Worid-Wide 

Web;' which is technically a "wide-area hypermedia information retrieval initiative aiming to 

eive universal access to a large universe of documents." To obtain access to the Worid-Wide 

20 Web, a computer operator uses software called a browser. The most popular browsers in the 

United States are Netscape Navigator and Microsoft's Internet Explorer. 

The operation of the Web relies on so-called hv^jertext for enabling user interaction. 

Hypenext is basically the same as regular text in that it may be stored, read, searched, and 

edited, with one important exception: a hypenext document contains links to other documents. 

25 For instance, selecting the word "hypertext" in a first document could call up secondan,' 
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documents to the user's computer screen, including, for example, a dictionary definition of 
"hypertext'' or a history of hypertext. These secondary documents would in turn include 
connections to other documents so that continually selecting terms in one documents after 
another would lead the user in a free-associative tour of information. In this way, hypertext 

5 links or "hyperlinks" can create a complex virtual web of connections. 

Hypermedia include hypertext documents which contain links not only to other pieces 
of text, but also to other media such as sounds, images and video. Images themselves can be 
selected to link to sound or documents. 

The standard language the Web uses to create and recognize hypermedia documents is 

10 the HyperText Markup ("HTML") Language. This language is loosely related to, but 
technically not a subset of, the Standard Generalized Markup Language ("SGML"), a 
document formatting language used widely in some computing circles. Web documents are 
typically written in HTML and are nothing more than standard text files whh formatting codes 
that contain information about layout (text styles, document titles, paragraphs, lists) and 

15 hyperlinks. 

HTML is limited to display fijnctions (text, animation, graphics, and audio) and form 
submission. Inherent in the basic HTML protocol (set of software-encoded rules governing 
the format of messages that are exchanged between computers) are design limitations that 
prevent the implementation of the type of program fijnctionality that is commonly used in 
20 today's desktop computers. Because of this limitation, it is impossible to enhance HTML 
documents with the features necessar\^ to support the Internet applications currently being 
sought by industry and consumers. 

Sun Microsystems and Netscape Communications have attempted to introduce 
additional program functionality through the implementation of Sun's Java programming 
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language as a browser plug-in. Microsoft, in addition to supporting Java, has introduced 
Active-X as a browser plug-in. Currently, after two years of development, both Java and 
Active-X are still failing to deliver working software. These languages are plagued by 
software errors that crash the newer operating systems. Even the developers of these 

5 languages, Sun and Microsoft, are having major problems with Java and Active-X applications 
that they have written to demonstrate the capabilities of the languages. 

Java, Active-X and almost all other programming languages use a programming 
paradigm based on the "C" programming language introduced by AT&T in the 1970's to 
develop the UNIX operating system. Although well suited for operating system development, 

10 "C" has two major drawbacks for Internet content deliver^'. The first drawback is that an 
entire program must be loaded before anything can be executed using the program. Because 
Internet content is open-ended, most applications can become very large, making downloading 
impractical due to the limited bandwidth of most Internet connections. Typical Java and 
Active-X applications take several minutes to download before they start running. The second 

1 5 drawback using programs based in '*C" is that content development is very inefficient. ''C" and 
programming languages based on the paradigm are currently used to produce software 
tools and utilities such as word processors, spreadsheets, and operating systems. Software 
developers can assign a large number of programmers to a long-term project, with the 
knowledge that repeated sales of the product to existing users will recover the large investment 

20 expenditure. However, developers of Internet content cannot afford this type of approach and 
have fallen back upon the very simple HTML protocol to economize development. 

However, even HTML is inadequate to enable or facilitate the conducting of interactive 
programming on the Internet. Although well adapted to passively providing muhimedia 
information, HTML is extremely limited in active and interactive software use and 
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development. Thus, companies seeking to conduct commercial activities on the Internet are 
seeking a programming tool or information-exchange methodology to replace HTML or to 
provide major enhancement to that language. In contrast to applications programs based on 
the "C" paradigm, Internet applications programming is generally not subject to muhiple uses. 
5 Rather an Internet program is consumed: the program is used only once by the typical user. 
Utilities-type software developed for individual computer use, such as word processors, spread 
sheets. E-mail, etc., can be sold at higher prices because the software is used again and again 
by any individual. 

Programming languages based on the "C" programming paradigm are awkward for 
10 programming interactions involving the computer's display screen. For example, a Microsoft 
proeram for the manipulation of sprites (graphic images that can move over a background and 
other graphic objects in a nondestructive manner) requires over 800 lines of code and over 
290 lines of assembler code. The same program written in the TenCORE language requires 
only six lines. 

15 TenCORE is a modular programming language designed in the early 1980's to facilitate 

the transfer of information between disk drives and RAM, panicularly for the delivery of 
interactive instruction ("Computer-Based Training"). At that time, disk drives were all slow 
and R.AM was inevitably small. In adapting to these hardware limitations, TenCORE 
introduced the use of small individual code modules for performing respective ftinctions, 

20 thereby enabling efficient performance as each code module loaded a single interaction fi-om 
the slow disk drives. Programming in the form of substantially independent code modules is 
open-ended, a necessary characteristic for educational software requiring the deliver)' of 
whatever remedial instruction is required by the individual student. TenCORE utilizes a 
program called an 'interpreter" that implements all basic required functions efficiently. The 
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interpreter has no content itself. The content comes from an unlimited number of small 
pseudocode modules which are loaded into the system memory and issue commands to the 
interpreter. In writing a program, the programmer's involvement is reduced to simply issuing 
commands, leaving all the difficulties of implementation to the interpreter. 
5 In contrast to TenCORE, "C" type programming includes a series of pre-written code 

libraries which are linked together as they are compiled. In theory, when a new 
microprocessor is designed, only the code libraries need to be rewritten and then all programs 
can be re-compiled using the new libraries. However, over the past twenty years the number 
of these code libraries has grown to a point where the original concept of rewriting for 

10 different microprocessors is no longer practical because of the difficulty in compensating for 
subtle differences between microprocessors. What remains is a complex and difficult 
programming syntax that takes years to master and is very difficult to debug. 
Objects of the Invention 

A general object of the present invention is to provide a method for communicating 

1 5 over a computer network. 

A more panicular object of the present invention is provide a method for enabling or 
facilitating the conducting of interactive programming over a computer network such as the 
Internet. 

A related object of the present invention is to provide a method for communicating 
20 software over a computer network, to enable an increased degree of interactive computer use 
via the network. 

Another object of the present invention is to provide a computing system for enabling 
or facilitating the conducting of interactive programming over a computer network such as the 
Internet. 
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It is a further object of the present invention to provide a computing system for 
communicating software over a computer network, to enable an increased degree of interactive 
computer use via the network. 

These and other objects of the present invention will be apparent from the drawings 
5 and descriptions herein. 
Summary of the Invention 

The present invention is directed to a computerized system and to an associated 
method for optimally controlling storage and transfer of computer programs between 
computers on a network to facilitate interactive program usage. In accordance with the 
10 method, an applications program is stored in a nonvolatile memory of a first computer as a 
plurality of individual and independent machine-executable code modules. In response to a 
request from a second computer transmitted over a network link, the first computer retrieves a 
selected one of the machine-executable code modules and only that selected code module from 
the memory and transmits the selected code module over the network link to the second 
1 5 computer. 

In one important field of use of the invention, the first computer is a server computer 
on a network. The second computer may be a user computer or a secondary server. 
Alternatively, the two computers may be two individual user computers on the network. 

Where the second computer is a user computer, the request for the executable code 
20 module arises because the user needs the code module to perform a desired function in the 
applications program. The user's computer does not have all of the code modules of the 
applications program and obtains new code modules only as those modules are needed. 
Because executable code of the applications program is broken down into individually 
executable modules, the program can be downloaded piecemeal module by module, as the 
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individual modules are needed by the user's execution of the program. Accordingly, the user 
need not wait for the entire program to be downloaded before the user can start using the 
program- 
Where the first computer and the second computer are a primary server and a 
5 secondary server, respectively, the present invention allows the primary server, when is too 
busy to handle a user request or task, to hand that request or task off to the secondary server. 
When a primary server receives a user request or task that the server cannot handle due to 
load, that request or task is forwarded preferably to the least busy secondary server available. 
The secondary server then processes the user request and responds to the client/user directly. 

10 If the secondary server does not have a code module, data file, or other resource required to 
handle the user request, the required code module, data file, or other resource can be 
transferred to the secondary server from the first server. This shunting of user requests 
contemplates the utilization of multiple secondary servers located on different Internet 
connections. The present invention thus eliminates most bandwidth and server load issues on 

1 5 the Internet and other computer networks. 

Of course, a server computer must shed its load before the server reaches its full 
capacity, thereby leaving enough system resources (processor, memory, etc.) fi*ee to fulfill any 
requests from a secondary server for resources necessary for the secondary server to fulfill a 
shunted user request or task. 

20 If a secondary server is unable to contact the client machine, the secondary server can 

forward the user request to another secondary' server for processing, since the other secondary 
server may be able to reach the client machine directly. 

A secondarj' server may also ser\'e as a backup server. In that case, the secondary 
server immediately requests all code modules, data files, and other resources from the primary* 
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server instead of waiting for a client request that requires one of those resources. When a 
client or secondary server makes a request of the primary server and discovers it to be 
inaccessible, the request can then be made of a backup server. In this way, if a primary server 
were to fail, the information that was on the primary server would still be accessible through 
5 the back-up server. To facilitate the maintenance of up-to-date resources on backup servers, 
the primary server sends notification packets to each of the backup servers whenever a 
resource is created or updated. The backup servers can then request the new, updated copy of 
the resource from the primary server, thereby remaining up to date with the primary server at 
all times. 

10 In order to optimize processing of user requests, a primary server stores in its memory 

a list of secondary servers on the network, the list including response times and load statistics 
(processor usage, etc.) for the respective secondary servers. The primary server periodically 
updates these response times, by sending echo packets to the secondary servers and measuring 
delays between the sending of the echo packets and a receiving of responses to the echo 
1 5 packets from the respective secondarv^ servers. The server also periodically updates the load 
statistics by requesting the current load statistics from the secondary servers. For processing a 
recently received user request, the primary server scans the list in memory and selects the 
secondary saver having the lightest load and shortest response time. 

For security purposes, code modules, as well as other resources such as data files, are 
20 transmitted in encrypted form. Encr>'ption is accomplished by placing the code modules, files, 
documents or other transmittable resources in the data area of an encryption packet. When an 
encrypted packet is received, it is decrypted and the code modules, files, documents or other 
transmittable resources subsequently handled pursuant to normal procedures. The 
enco'ption/decryption process can be handled by a plug-in code module. Any number of plug 
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in encryption code modules may exist in a data and code transfer system in accordance with 
the invention at any one time. The header of an encryption packet contains an indication of 
which plug-in encryption code module must be used for decryption purposes. 
Encryption/decryption code modules can be delivered real time by a code module exchange 
5 protocol. 

To fijrther enhance the security of the system, the primary server stores a list of user 
authentification codes in its memory. Upon receiving a request, e.g., for a machine executable 
code module, from another computer, the primary server compares a user authentification code 
in the request with the stored list of user authentification codes. The primary server proceeds 

10 with retrieving and transmitting a selected machine-executable code module only if the user 
authentification code in the request matches a user authentification code in the stored list. 
Where an incoming request for a machine-executable code module is contained in an 
encryption packet, the server decrypts the encryption packet prior to the comparing of the user 
authentification code in the request with the list of user authentification codes in the memory. 

1 5 Encrypting and decrypting of encryption packets, as well as the checking of user 

authentification codes, may be performed by the secondary server(s). Whatever programming 
or data required for carrying out these security measures can be transmitted from the primary 
server in accordance with the present invention. 

The present invention provides for the updating of an applications program in users' 

20 machines. When a user sends a request for a code module to a server, the request includes a 
specification of the version of the program code sought. The server processing the request 
checks whether the requested version is the latest version available. W^hen a newer version of 
a requested code module is available, the server informs the user and inquires whether the user 
could use the newer version of the requested module. The user could then send a request for 
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the updated version of the desired code module. 

If the updated version of the desired code module is incompatible with older versions 
of other code modules, the older version of the desired code module will be transmitted from 
the server to the user. If the older version is not available, the user may have to request 
5 transmission of the newer versions of several additional modules. 

Generally, it is contemplated that machine-executable code modules are written in a 
user-friendly programming code such as TenCORE. In that case, a software-implemented 
interpreter unit of the user computer translates the code modules from the programming code 
into machine code directly utilizable by the user computer. When such an interpreter is used, 
1 0 the interpreter itself can be updated in the same fashion as an application program or code 
module. For purposes of updating the interpreter, the interpreter is treated as a single large 
code module. 

In a related method in accordance with the present invention for optimally controlling 
storaee and transfer of computer programs between computers on a network to facilitate 

15 interactive program usage, a ponion of an applications program is stored in a first computer. 
The applications program comprises a plurality of individual and independent machine- 
executable code modules. Only some of the machine-executable code modules are stored in 
the first computer. This method includes executing at least one of the machine-executable 
code modules on the first computer, transmitting, to a second computer via a network link, a 

20 request for a further machine-executable code module of the applications program, receiving 
the further machine-executable code module at the first computer from the second computer 
over the network link, and executing the further machine-executable code module on the first 
computer. 

To fiirther facilitate program transfer on the network, the first computer may conduct 
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an investigation into server availability. Pursuant to this feature of the invention, a request is 
sent from the first computer (e.g., a user) to a further computer (e.g., a primary server) for a 
list of servers (e.g., secondaries) on said network. After transmission of the list of server to 
the first computer, response times for the server are determined by (a) sending echo packets 

5 from the first computer to the servas, (b) measuring, at the first computer, delays between the 
sending and receiving of the echopackets, (c) querying the servers as to current server load 
(processor usage, etc.) The request for a further machine-executable code module is sent to 
the server having the lightest load and shortest measured response time. The list of servers can 
be cached in memory by the first computer to facilitate fijrther access to the information in the 

0 event that the server from which the list was requested becomes unavailable or is too busy to 
handle the request- 
In the event that there has been an update in a requested code module, a request from 
the first computer for a particular version of the code module may trigger an inquiry as to 
whether the first computer could use the updated version of the code module. If so, the first 

5 computer transmits a second requests, this time for the updated version of the desired code 
module. 

Where the two computers are both user machines, the method of the present invention 
facilitates interactive processing. Each computer executes one or more selected code modules 
in response to the execution of code modules by the other computer. Thus, both computers 
20 store at least some of the machine-executable code modules of the applications program. 
Occasionally one computer will require a code module which it does not have in present 
memor)'. Then the one computer can obtain the required code module from the other 
computer. If the other computer does not have the required module, a request may be made to 
a server on which the applications program exists in its entirety. 
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Where the machine-executable code modules are written in a user-friendly 
programming code, each user computer includes an interpreter module implemented as 
software-modified generic digital processing circuits which translates the code modules from 
the programming code into machine code utilizable by the respective computer. 
5 In accordance with a feature of the present invention, the machine-executable code 

modules each incorporate an author identification. The method then fiirther comprises 
determining, in response to an instruction received by a user computer over the network and 
prior to executing the one of the machine-executable code modules on the user computer, 
whether the panicular author identification incorporated in the one of the machine-executable 
1 0 code modules is an allowed identification. The user computer proceeds with code module 
execution only if the particular author identification is an allowable identification. Generally, 
the instruction determining whether a code module is written by an allowed author is a list of 
blacklisted authors. 

The author identification feature of the invention severs to prevent an author from 
1 5 creating a virus or other malicious program and distributing it using the code module exchange 
protocols of the present invention. All compilers supporting the coding of individual machine- 
executable code modules in accordance with the present invention will incorporate a respective 
author identification code into each machine-executable code module. The author 
identification is unique to each author. When a malicious program is discovered, the 
20 identification of the author may be distributed throughout the network to blacklist that author 
and prevent the execution of code modules containing the blacklisted author^s identification. 
As an additional advantage, this feature will discourage users from distributing illegal copies of 
the authoring package, since the respective users will be held responsible for any malicious 
programs written under their author identification. 
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The storing of applications program modules in a user computer may include caching 
the code modules in a nonvolatile memory of the user computer. 

It is to be noted that the present invention permits the transmission during user 
computer idle time of code modules whose use is anticipated. A request from the user 
5 computer is transmitted to a server or other computer for a machine-executable code module 
during an idle time on the user computer. 

A computing system comprises, in accordance with the present invention, digital 
processing circuitry and a nonvolatile memory storing general operations progranuning and an 
applications program. The applications program includes a plurality of individual and 
10 independent machine-executable code modules. The memory is connected to the processing 
circuitry to enable access to the memory by the processing circuitry. A communications link is 
provided for communicating data and programs over a network to a remote computer. A code 
module exchange means is operatively connected to the memory and to the communications 
link for retrieving a single code module from among the machine-executable code modules and 
1 5 transferring the single code module to the remote computer in response to a request for the 
single code module from the remote computer. 

As discussed above, the computing system of the present invention may be a server 
computer on the network. The server's memory may contain a list of secondary servers on the 
network, the list including response times for the respective secondary servers, The computing 
20 system then further comprises a detection circuit, generally implemented as software-modified 
generic digital processing circuitr\^ for detecting an overioad condition of the computing 
system. A server selector, also generally implemented as software-modified generic digital 
processing circuitry, is operatively connected to the detection circuit, the memory and the 
communications link for determining which of the secondary' servers has a shortest response 
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time and for shunting an incoming user request to the secondary server with the shortest 
response time when the overload condition exists at a time of arrival of the user request. 

Thus, the remote computer transmitting a code-module request to the computing 
system may be a secondary server to which a user request has been shunted. The requested 
5 single code module is required for enabling the remote computer to process the user request. 
On behalf of the computing system. 

Pursuant to another feature of the present invemion, the computing system further 
comprises an updating unit, preferably implemented as software-modified generic digital 
processing circuitry, operatively connected to the memory and the communications link for (1) 
1 0 periodically sending echo packets to the secondary servers, (2) measuring delays between the 
sending of the echo packets and a receiving of responses to the echo packets from the 
respective secondary servers, and (3) updating the response times in the list in accordance with 
the measured delays. 

For security purposes, the memory of the computing system may contain a stored list 
1 5 of user authemification codes. The computing system then includes a comparison unit, 
preferably implemented as software-modified generic digital processing circuitry, for 
comparing a user authentification code in an incoming request with the list of user 
authemification codes in the memory and for preventing code-module retrieval and 
transmission in the event that the user authemification code in the request fails to correspond 
20 to any user authentification code in the list. 

Where incoming requests for code modules are contained in encryption packets, the 
computing system ftirther comprises a software-implememed decryption circuit connected to 
the communications link and the comparison unit for decr^'pting the encryption packet prior to 
the comparing of the user authentification code in the request with the list of user 
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authentification codes in the memory. 

In accordance with another feature of the invention, the computing system includes 
means for determining whether a requested code module has an updated version and for 
responding to the request with an invitation to the remote computer to accept the updated 
5 version of the requested code module. 

It is contemplated that the machine-executable code modules are written in a user- 
friendly programming code. Where the computing system uses the applications code itself, the 
computing system further comprises an interpreter for translating the programming code into 
machine code directly utilizable by the processing circuitry. The interpreter may take the form 
10 of generic digital processing circuit modified by programming to perform the translation 
function. 

A computing system (e.g., a user computer on a network) also in accordance with the 
present invention comprises a memory storing a portion of an applications program having a 
plurality of individual and independent machine-executable code modules, only some of the 

15 machine-executable code modules being stored in the memory. A digital processing circuit is 
operatively connected to the memory for executing at least one of the machine-executable code 
modules. A communications link is provided for communicating data and programs over a 
network to a remote computer. A code module exchange unit is operatively connected to the 
memory and to the communications link for communicating with a remote computer (e.g., a 

20 server on the network) via a network link to obtain from the remote computer a further 

machine-executable code module of the applications program. The digital processing circuitrv' 
is operatively tied to the code module exchange unit for executing the further machine- 
executable code module upon reception thereof from the remote computer. 

When a client or user machine is not running at full capacity (processor idle time is over 
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a given threshold and network traffic is under a given threshold), that machine can look for 
other client machines on the same virtual network that may be in the midst of a processor- 
intensive task and take on some of the load. If necessary, the code modules to handle that task 
can be transferred to the idle client machine. It is possible for clients working together on the 
5 same project to communicate with each other using a custom sub-protocol. This client-side 
distributed processing significantly improves the performance of processor-intensive tasks. 

The present invention provides a programming paradigm which addresses the Internet 
content developer's specific needs. A software system and computer communications method 
in accordance with the present invention delivers rapidly over the Internet, provides a practical 
10 proeramming paradigm that suppons rapid economical development of content, and facilitates 
new capabilities in Internet software and systems management. 

TenCORE, a modular programming language designed to use small efficient code 
modules for facilitating program transfer between disk drives and central processing units of 
desktop computers, may be easily modified to carry out the present invention. Minimal 
1 5 modifications require the adapting of the transfer capabilities to work over network links. 

The present invention arises in part from the realization by the inventors that the 
problems facing the developers of TenCORE in 1980 are the same problems that software 
designers face today when dealing with the Internet and its limited bandwidth and slow 
connections. It was perceived that Internet applications must be open-ended and programming 
20 must be delivered rapidly in spite of bandwidth limitations. Thus, the solution provided by 
TenCORE is usefiil in solving today's problems with interactive software on the Internet. The 
modular programming of TenCORE enables rapid Internet performance because a single 
TenCORE Net programming module can be quickly downloaded over the Internet. The 
TenCORE Net programming modules are TenCORE programming modules which are 
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modified to enable downloading from Internet servers instead of from a microcomputer's disk 
drive. 

TenCORE and TenCORE Net are interpreted languages, i.e., they serve to translate 
into machine language pseudocode programs and to perform the indicated operations as they 

5 are translated. "Pseudocode" is unrelated to the hardware of a particular computer and 

requires conversion to the code used by the computer before the program can be used. Once 
the TenCORE Net interpreter is installed on a computer equipped with an Internet connection, 
clicking with a mouse on a conventional World-Wide Web hyperlink that points to a 
TenCORE Net application automatically bypasses the Internet browsing software and launches 

10 the application. Because only the required modules are sent over the Internet and because the 
TenCORE Net modules are ver\' small, Internet performance is very fast. 
Brief Description of the Drawing 

Fig. 1 is a block diagram of a computer network with various servers and user 
computers, which transmit executable programs to one another pursuant to the present 

15 invention. 

Fig. 2 is a block diagram of a primary' ser\'er in accordance with the present invention. 

Fig. 3 is a block diagram of a user computer in accordance with the present invention. 

Fig. 4 is a flow chart diagram illustrating a maintenance loop in the operation of 
selected program-modified processing circuits in the primary server of Fig. 2 and the user 
20 computer of Fig. 3. 

Fig. 5 is a flow chart diagram illustrating a loop for processing an incoming data packet 
in the operation of selected program-modified processing circuits in the primary server of Fig. 
2 and the user computer of Fig. 3. 

Figs. 6A and 6B are a flow chart diagram illustrating further operations relating to the 
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processing of an incoming request for a code module in accordance with the present invention. 

Fig. 7 is a flow chart diagram illustrating a subroutine for processing an incoming 
resource request packet in the operation of selected program-modified processing circuits in 
the primary server of Fig. 2 . 
5 Fig- 8 is a flow chart diagram illustrating a maintenance loop in the operation of 

selected program-modified processing circuits in the primary server or a secondary server of 
Fig. 2. 

Fig. 9 is a flow chart diagram illustrating a subroutine for processing an incoming 
resource request packet in the operation of selected program-modified processing circuits in 
10 the primary server of Fig. 2 . 

Fig. 10 is a flow chart diagram illustrating a maintenance loop in the operation of 
selected program-modified processing circuits in the primary server or a secondary server of 
Fig. 2 

Description of the Preferred Embodiments 

1 5 As illustrated in Fig. 1 , a computer network comprises a plurality of user computers 1 

operaiively connected to a primary server computer 14 via a complex of network links 16. 
The primary server 14 stores, in an area 1 8 of a nonvolatile memory 20 (Fig. 2), an 
applications program which may be desired for use on one or more user computers 12. The 
term "applications program'' as used herein refers to any executable collection of computer 

20 code other than operating systems and other underlying programming for controlling basic 
machine functions. 

As further illustrated in Fig. 1. the network includes a plurality of secondary* servers 2 
which are available for assisting primary server 14 in responding to requests from user 
computers 12. More particularly, as shown in Fig. 2, primary' computer 14 includes an 
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overload detector 24 which continually monitors a queue of jobs or tasks which primary server 
14 has to perform. Overload detector 24 determines whether the number and size of tasks in 
the queue has exceeded a predefined threshold. Once that threshold is reached, overload 
detector 24 signals a secondary server selector 26 which accesses an area 28 of memory 20 to 
5 identify a secondary server 22 which is least busy. To that end, memory area 28 contains a list 
of secondary servers 22 as well as measured response limes for the respective servers. 

The response times in the secondary- server list in memory area 28 are periodically 
measured by dispatching echo packets to each secondary server 22 and measuring the delays 
between the transmission of the respective echo packets from primary server 14 and the receipt 

10 of responses from the respective secondar>' servers 22. To accomplish the measurement, 
primary server 14 and, more paniculariy, a processing unit 30 thereof contain an echo packet 
dispatcher 32 and a response-time monitor 34. Upon transmitting an echo packet to a 
secondary server 22 via a network communications interface 36 at primary server 14, 
dispatcher 32 notifies response-time monitor 34 as to the transmission of a packet and as to the 

1 5 secondar>' server 22 to which the transmission was made. Monitor 34 counts out the time 
between the transmission of the echo packet and the arrival of a response from the respective 
secondary server 22 via network links 16 and communications interface 36. A response-time 
update unit 38 is connected to response-time monitor 34 and to memory area 28 for writing 
updated response times in the secondary server list stored in memory area 28. 

20 The applications programs store 18 in memory 20 contains a multiplicity of individual 

and independent machine-executable code modules. Accordingly, a user computer 12 working 
with the applications program need not be loaded with the entire program in order to begin 
processing operations. In the event that the user's execution of the applications program 
requires a code module not contained in the user's computer memor>', a request is transmitted 
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from the user computer 23 over network links 16 to primary sender 14. If primary server 14 is 
not overloaded, it retrieves the requested code module from program store 1 8 and transmits it 
over communications interface 36 and network links 16 to the user computer which made the 
request. 

5 Processing unit 30 of primary server 14 includes a code-module exchanger 40 which 

processes incoming requests for code modules of the applications program or programs stored 
in memory area 18. Exchanger 40 cooperates with a version detector 42 which consults the 
applications program store 1 8 to determine whether a requested version of a particular code 
module is the latest version in store 18. If not, version detector 42 and code module exchanger 

10 40 transmit an inquiry to the resting computer as to whether the latest version of the desired 
code module is utilizable by the requester. If the newer version of the desired code module can 
be used in place of the older version, the newer version is transmitted over communications 
interface 36 and network links 16. 

Code modules, as well as other resources such as data files, may be transmitted in 

1 5 encrypted form for security purposes. Encryption is accomplished by placing the code 

modules, files, documents or other transmittable resources in the data area of an encryption 
packet. When an encrypted packet is received by processing unit 30 via communications 
interface 36, the packet is forwarded via generic processing circuits 50 to an 
encryption/decryption unit 44 for deciphering. Encryption/decryption unit 44 consults a 

20 memory area 46 containing a plurality of possible encryption keys and selects an encryption 
key identified by header information in the encryption packet containing the user request. 
Upon decryption of the incoming encr\'ption packet, the user request or code module exchange 
packet contained therein is forwarded to code-module exchanger 40 for processing. The 
encrj'ption/decryption process can be handled by a plug-in code module performing the 
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functions of encryption/decryption unit 44 and memory area 46. Any number of plug-in 
encryption code modules may exist in a data and code transfer system at any one time. The 
header of an encryption packet contains an indication of which plug-in encryption code module 
must be used for decryption purposes. 
5 To further enhance the security of a computer network which has protocols for the 

exchange of executable code modules, primary server 14 stores a list of user authentification 
codes in a memory area 48. In response to a request, e.g., for a machine-executable code 
module, from another computer, comparator 52 in processing unit 30 compares a user 
authentification code in the request with the list of user authentification codes stored in 

1 0 memory area 48. Code module exchanger 40 proceeds with retrieving and transmitting a 
selected machine-executable code module only if the user authentification code in the request 
matches a user authentification code in the stored list. Where an incoming request for a 
machine-executable code module is contained in an encryption packet, encryption/decryption 
unit 44 deciphers the encr>'ption packet prior to the comparing by comparator 52 of the user 

15 authentification code in the request with the list of user authentification codes in memory area 
48. Where a user request is relayed to a secondary server 22 chosen by selector 26, the 
secondary server incorporates an encryption/decryption unit and an authentification-code 
comparator for encrypting and decrypting of encryption packets and the checking of user 
authentification codes, may be performed by the secondar>' server(s). Whatever programming 

20 or data required for carrying out these security measures can be transmitted from primary' 
server 14 to the selected secondary server 22. 

As illustrated in Fig. 3, a processing unit 54 of a user computer 12 includes a code- 
module exchanger 56 which generates requests for desired code modules of an applications 
program as those code modules are required during execution of the applications program by 
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the user. The code-module requests are transmitted to code-module exchanger 40 of primary 
server 14 via a network communications interface 58 at user computer 12, network links 16 
(Fig. 1) and communications interface 36 at primary server 14. 

In a security enhanced system, processing unit 54 of user computer 12 includes a 
5 encryption/decryption unit 60 which inserts code-module request packets, as well as other 
information transfer packets, imo the data areas of respective encryption packets whose 
encryption keys are selected from a plurality of keys stored in an area 62 of a nonvolatile 
memory 64 of user computer 12. Again, the encryption/decryption process at user computer 
12 can be handled by a plug-in code module performing the functions of encryption/decryption 
1 0 unit 60 and memory area 62. The header of an encryption packet generated by encryption- 
decryption unit 60 comains an indication of which plug-in encryption code module at primary 
server 14 must be used for decryption purposes. 

In a further security enhancemem used to protect the computing system of Fig. 1 in 
general and user computer 12 in particular from computer viruses and other malicious 
1 5 programming, processing unit 54 is provided with an author idemification comparator 66 
which accesses an author identification list 68 in memory 64. Author identification list 68 is 
periodically updated by author idemification comparator 66 and other function-converted 
blocks in generic processing circuits 70 in response to incoming instructions firom primary 
server 14. Author idemification list 68 comains a list of allowed authors or, perhaps more 
20 efficiently, a list of authors who have been blacklisted owing to their passing of viruses or other 
malicious programming onto the network. Prior to the use of an incoming machine-executable 
code module. The author identification in a packet header is checked by comparator 66 to 
determine that the author of the particular code module has not been blacklisted. If the author 
is allowed to produce executable code modules for user computers 1 2, processing of the 
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incoming code module proceeds normally. If, on the other hand, the author of the incoming 
code module has been blacklisted, then the code module is never executed and may be 
discarded prior to storage in an applications program store 72 in memory 64. 

As discussed above with reference to Figs. 1 and 2, primary server 14 may occasionally 

5 hand off an incoming user request to a secondary server 22, depending on the load condition of 
the primary server and the secondary servers. Generally, this handing off of responsibility for 
responding to users' requests is transparent to the users, i.e., the processing of users' requests 
proceeds without knowledge or intervention by the users. It is also possible for user 
computers 12 to take over selection of a secondary computer 22 from primary computer 14. 

10 To that end, processing unit 54 of user computer 12 is provided with a secondary server 

selector 74 which accesses a list 76 of secondary-servers in memory 64. Generally, selector 74 
selects a secondary server 22 with a smallest response time relative to the respective user 
computer 12. To that end, processing unit 54 further includes an echo packet dispatcher 78, a 
response-time monitor 80 and a response-time update unit 82. Dispatcher 78 sends echo 

1 5 packets to secondary servers 22 via communications interface 58 and network links 16 (Fig. 
1), while monitor 80 determines the delays of responses from the various secondary servers. 
Update unit 82 corrects response time data in list 76 in accordance with measurements carried 
out by dispatcher 78 and monitor 80. It is contemplated that the updating of secondary-server 
response times in list 76 is implemented only when user computer 12 requires a user module or 

20 other resource from primary server 14 and that server is too busy to handle the user request. 

Processing unit 54 of a user computer 12 has a distributed processing circuit 84 which 
enables processing unit 54 to share the processing of large tasks with other user computers in 
the network. Thus, when a user computer is not running at full capacity (processing unit 54 is 
more than 50% idle and there is no network traffic), that distributed processing circuit 84 
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looks for other user computers 12 that may be in the midst of a processor-intensive task and 
enable transfer of some of the load to the processing unit 54 of the respective user computer 
12. If necessary, the code modules to handle that task can be transferred to the idle user 
computer 12. This client-side distributed processing significantly improves the performance of 
5 processor-intensive tasks. 

Processing unit 54 of a user computer 12 also contains a metered delivery and billing 
circuit 86 which controls access to content which must be paid for. Credit registers 88 in 
memory 64, accessible by circuit 86, store credits which the particular user has against 
respective accounts. When credit in an account maintained or monitored by primary server 14 
1 0 is low, circuit 86 may arrange for the transfer of more credit from primary server 14 to the 
particular user. Metered delivery and billing circuit 86 includes a billing method to pay for the 
credit. Generally, credit requests and responses thereto should be encrypted. 

Processing unit 54 of a user computer 12 additionally includes a unidirectional data 
submission and collection circuit 90 which accesses data files 92 in memory 64 for purposes of 
1 5 uploading those data files to primary server 14 or to a selected secondary sen/er 22. Data 
submission and collection circuit 90 is operative when the user computer does not need to read 
the data back from the server. This circuit is particularly useful for on-line orders, form 
submission, and data collection (including statistical data) among other things. 

Generally, packets that contain data to be written must be sent directly to the primary 
20 server 14 and cannot be shunted. This prevents conflicts between different versions of the 
resource that was written to. Data written back to the server should require user 
authentification. User authentification should be used even if the write-back will be done only 
by a program under author control. In that case, user identification codes and passwords can 
be built into the program. The reason for this is to prevent another author from writing a 

BNSDOCID <WO O907007A2 I > 



wo 99/07007 



PCT/US98/15627 



25 

program that would write back to the same data and possibly corrupt it. 

Applications program code modules stored in memory area 1 8 (Fig. 2) and module 
store 72 (Fig. 3) are written in TenCORE, a modular programming language originally 
designed to use small efficient code modules for facilitating program transfer between disk 
5 drives and central processing units of desktop computers. TenCORE is easily modified, for 
example, to adapt the code transfer capabilities to operate over network links. The program so 
modified for use on user computers 12, primary server 14 and secondary servers 22 may be 
called "TenCORE Net." 

TenCORE Net uses small individual code modules for performing respective functions, 
10 thereby enabling efficient performance as each code module is downloaded a single interaction 
fr-om primary server 14 or a selected secondary server 22. Programming in TenCORE Net is 
open-ended, so that a user computer 12 executes instructions of an applications program when 
that applications program is only partially stored in program store 72 of memory 64. 

The code modules held in memory store 72 are in a user-friendly pseudocode language 
1 5 which must be translated or interpreted for direct machine use. To that end, processing unit 54 
includes a program or programmed interpreter circuit 94 that implements all basic required 
functions efficiently. The interpreter has no content itself Content is derived from a 
potentially unlimited number of small pseudocode modules which are loaded into memory 
store 72 and which effectively issue commands to interpreter 94. In writing a program, the 
20 programmer's or author's involvement is reduced to simply issuing commands, leaving all the 
difficulties of implementation to the interpreter. 

TenCORE may be modified in two ways to enable network use. First, a subroutine or 
set of instructions may be inseaed before each call line of computer code for checking whether 
the code intended for execution exists in applications program memory area 72. If not, code 
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module exchanger 56 is instructed to obtain the required code module from primary server 14. 
Once the required code module has been downloaded into memory area 72, it is called and 
translated by interpreter circuit 94 prior to execution by processing circuits 70. 

Through the use of modular applications programs and code-module exchangers 40 
5 and 56, the control of computer program storage and transfer between computers 12, 14, 22 
on a network is optimized, thereby facilitating interactive program usage. An applications 
program stored in nonvolatile memory area 1 8 of primary server 14 may be transferred to 
various user computers 12 in modular fashion. In response to a request transmitted over 
network links 16 from a user computer 12 or a selected secondary server 22, primary server 14 
10 retrieves a selected machine-executable code module and only that selected code module from 
memory area 18 and transmits the selected code module over network links 16 to the user 
computer or secondary server. 

Where the applications program is, for instance, a drawing or painting program, a user 
computer 12 may be instructed to draw a three-dimensional geometric figure such as a 
1 5 truncated pyramid. If processing circuits 70 discover that the applications program in program 
store 72 is missing a code module required for performing that task, code module exchanger 
56 requests that the requisite module be transferred from primary server 14, In response to 
that request, version detector 42 may fmd that a later version of the desired module exists and 
inquire of code-module exchanger 56 whether the later version would be acceptable for use by 
20 the respective user computer. 

Thus, user computers 12 do not have all of the code modules of the applications 
program and obtain new code modules only as those modules are needed. Because executable 
code of the applications program is broken down into individually executable modules, the 
program can be downloaded piecemeal, module by module, as the individual modules are 
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needed by the user's execution of the program. Accordingly, the user need not wait for the 
entire program to be downloaded before the user can start using the program. 

Similarly, a selected secondary server 22 can begin to process a transferred or shunted 
user request and respond to the client/user directly, without having the entire applications 
5 program and other resources relating to the handling of the program's distribution by the 
primary server 14. If the selected secondary server does not have a code module, data file, or 
other resource required to handle the user request, the required code module, data file, or 
other resource can be transferred to the secondary server from the primary server. Secondary 
servers 22 are thus provided with code module exchangers similar to exchangers 40 and 56. 
10 Of course, primary server 14 must shed its load before that server reaches its ftill 

capacity, thereby leaving enough system resources (processor, memory, etc.) ft-ee to fulfill any 
requests from a secondary server for resources necessary for the secondary server to fiilfiU a 
shunted user request or task. 

In security sensitive networks, secondary servers 22 are equipped with 
1 5 encr>'ption/decryption units like unit 44, as well as authentification comparators 52. Where an 
incoming request for a machine-executable code module is contained in an encryption packet, 
the secondary server decrypts the encryption packet prior to the comparing of the user 
authentification code in the request with a list of user authentification codes in memory. 
WTiatever programming or data required for carrying out these security measures can be 
20 transmitted fi*om primary server 14. 

If a secondary server is unable to contact the client machine, the secondary server can 
forward the user request to another secondar>' server for processing, since the other secondary 
server may be able to reach the client machine directly. 

Code module exchanger 56 of processing unit 54 facilitates interactive processing on a 
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network. Each user computer 12 executes one or more selected code modules in response to 
the execution of code modules by the other computer. Thus, both computers store at least 
some of the machine-executable code modules of the applications program. Occasionally, one 
computer will require a code module which it does not have in present memory. Then the one 
5 computer can obtain the required code module from the other computer. If the other 

computer does not have the required module, a request may be made to a server on which the 
applications program exists in its entirety. 

Thus, clients or users on a network are able to exchange code modules with one 
another If a first user and a second user are engaged in an interactive whiteboarding session 
10 and the first user starts drawing with a tool that the second user does not have in her version of 
the whiteboarding program, the code module or modules for that tool can be transferred 
automatically from the first user's computer to the second user's computer. 

It is to be noted that code module exchanger 56 may be instructed to initiate the 
transmission during user computer idle time of code modules whose use is anticipated. A 
1 5 request from the user computer 12 is transmitted to primary sender 14 or other computer for a 
machine-executable code module during an idle time on the user computer. Resource requests 
that are generated for idle-time downloading should be flagged as such, so that code module 
exchanger 56 can assign different priorities from standard requests for load balancing and 
distribution purposes. The status of a resource request can be upgraded to real time from idle 
20 time in the event that the user attempts to access the associated section of the application. 

It is to be noted that the various dedicated function blocks of processing units 30 and 
54 are generally and preferably implemented as software-modified generic digital processing 
circuits. Accordingly, code-module exchanger 40 and 56 are characterizable as protocols for 
the exchange of code modules between a ser\'er 14 or 22 and a user computer 12. This code 
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module exchange protocol is considered a subprotocol of a Modularized Code Master 
Protocol ("MCMP") which handles load distribution, user authentification and encryption. 
Load distribution is more particularly handled in primary server 14 by processor overload 
detector 24 and secondary-server selector 26, while user authentification and encryption are 
5 handled in primary server and secondary servers 22 by comparator 52 and 
encryption/decryption unit 44, 

The MCMP has four subprotocols, namely, the Code Module Exchange Protocol 
("CMXP"), the Uni-Directional Data Submission and Collection Protocol ("UDSCP"), the 
Metered Delivery and Billing Protocol ("MDBP"), and the Distributed Processing Protocol 

1 0 (DPP"). The Code Module Exchange Protocol is realized by code-module exchanger 40 in 
processing unit 30 of primary server 14 and secondary servers 22 and by code-module 
exchanger 56 in processing unit 54 of user computers 12. The Uni-Directional Data 
Submission and Collection Protocol is implemented by circuit 90 in user computers 12 and by 
corresponding non-illustrated program-modified processing circuitry in primary server 14. 

1 5 The Metered Delivery and Billing Protocol finds realization by circuit 86 in user computers 12 
and by corresponding non-illustrated program-modified processing circuitry in primary server 
14. The Distributed Processing Protocol takes the form of circuit 84 in processing unit 54 of 
user computers 12. 

Fig. 4 illustrates operations undertaken by echo dispatcher 32, response-time monitor 
20 34, and update unit 38 as well as other processing circuits of processing unit 30 of primary 
server 14 to maintain an updated list 28 of the availability of secondary servers 22 . The same 
steps may be performed by echo dispatcher 78, response-time monitor 80, and update unit 82 
as well as other processing circuits of processing unit 54 of user computer 12 to obtain an 
updated list of secondary server response times. In an inquiry 100, echo dispatcher 32 or 78 or 
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generic processing circuits 50 or 70 query whether the time since the last echo testing is 
greater than a predetermined maximum period TMR. If the maximum period has been 
exceeded, echo packet dispatcher 32 or 78 transmits, in a step 102, an echo packet to the 
secondary server 22 which was tested the least recently. Response-time monitor 34 or 80 
5 determines in an inquiry 104 whether a response has been received from the targeted secondary 
server 22. If a response has not been received and if a prespecified number of measurement 
attempts has not been exceeded, as determined at a decision junction 106, another echo packet 
is dispatched in step 102. If a response is received from the targeted secondary server 22, 
update unit 38 or 82 then records, in list 28 or 76, the time between the initial packet 
10 transmission by dispatcher 32 or 78 and the receipt of the echo packet by monitor 34 or 80. 
This recordation is effected in a step 108. If the number of attempts at secondary-server 
response-time measurement has exceeded the pre-specified number, as determined at decision 
junction 106, the server is marked in list 28 or 76 as being unavailable (step 110). Also a 
message or alert signal may be generated to inform a server overseer. If at query 100, it is 
15 determined that the time since the last echo testing is less than predetermined maximum period 
TMR, processing unit 30 or 54 investigates at 1 12 whether there is a packet in a MCMP 
incoming packet queue. If not, the maintenance loop of Fig. 4 is re-entered. If so, a packet 
processing operation 1 14 is executed. It should be noted that the MCMP incoming packet 
queue contains both packets received from the network, and packets placed into the queue by 
20 the MCMP protocol. 

Figs. 6 A and 6B illustrate operation 1 14 carried out under the MCMP protocol by 
processing unit 30 of primary server 14 or of a secondary server 22 selected for overflow 
handing. In an initial inquiry 124, overioad detector 24 decides whether processing unit 30 is 
too busy to handle the incoming packet (which may be, for example, a user request for a code 
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module). If so, processing circuits 50 investigate the MCMP packet header at a junction 126 
to determine whether the packet can be shunted to a secondary server 22. If so, a further 
investigation 128 is conducted to determine whether the incoming packet has already been 
shunted. If the packet was sent to the server directly by the originating computer (i.e., not 

5 shunted), secondary-server selector 26 accesses list 28 in a step 130 to find the secondary 
server 22 with the lightest load. At a subsequent inquiry 132, processing unit 30, and more 
particularly, server selector 26, determines whether the selected secondary server is suitable for 
transfer of responsibility for the incoming packet. If the selected secondary server is suitable, 
the packet is flagged as the result of a service hand-off and forwarded to the selected 

10 secondary' server (step 134). 

If the secondary server selected in step 130 is not suitable for a hand-off, for example, 
if the response time of the secondary server is greater than a predetermined maximum, as 
determined at inquiry 132, a query 136 is made as to whether an incoming packet is the result 
of a service hand-off. This inquiry 136 is also made if the packet cannot be shunted, as 

15 determined at decision junction 126. 

If an incoming MCMP packet is the result of a service hand-off, as determined at query 
136, processing circuits 50 undertake an investigation 138 as to whether the requested 
resource is available. If the resource is available, processing circuits 50 ask at 140 whether the 
resource has passed a pre-assigned expiration date. If so, a signal is transmitted in a step 142 

20 to the source of resource to determine if a newer version of the resource is available. If a new- 
version is available, as ascertained at a decision junction 144. a request for the newer version 
of the resource is transmitted to the source in a step 146. This request is flagged as non- 
shuntable and should be additionally flagged as a priority request. 

Prior to the processing of an incoming packet, e.g., a user request for a code module, 
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processing unit 30 examines the header information in the incoming packet at an inquiry 150 to 
determine whether the packet contains user authentification information. Where user 
authentification information is found, the former encryption status of the packet is determined 
at 152. If the packet was not encrypted, a message is generated in a step 154 to report that the 

5 user authentification failed. If the incoming packet was encrypted, the MCMP header 
information is checked at 1 56 to determine if the source server is specified. If there is no 
source server specification, user authentification failure is reported in step 154. If there is a 
source server specified in the MCMP header information and if that source server is not the 
host server, as determined at a decision junction 158, an investigation 160 is conducted (by 

10 authentification code comparator 52) as to whether memor\^ area 48 has a non-expired, cached 
copy of the user authentification data. If there is no non-expired, cached copy of the user 
authentification data in memorv' area 48. comparator 52 induces processing circuits 50 to 
obtain the user's authentification data from the source server and to store that data in memory 
area 48 (step 162). If a user's password contained in the MCMP packet header information 

1 5 does not match the cached password, as determined by comparator 52 in an evaluation 164 or 
if the user is not listed with the source server, as discovered by processing circuits 50 at a 
check point 166, the user authentification is reported as failed in a step 168. A report as to 
user authentification failure (step 154) is also made if the source server is the host server 
(decision junction 158) and if comparator 52 finds in an investigation 170 that the user 

20 authentification data in the packet header does not correspond to any user authentification data 
in memor\^ area 48. 

Once comparator 52 finds a match between the authentification code in an incoming 
packet and the user's authentification code in memon,' area 48, as determined in investigation 
170 or in evaluation 164, or if the incoming packet did not contain a user authentification code, 
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then evaluation 171 determines whether the packet should be handled directly by the MCMP 
protocol, or by another protocol. If evaluation 171 determines that the packet should be 
handled by the MCMP protocol directly, then the packet is processed accordingly at a step 173 
as illustrated in Fig. 5. If evaluation 171 determines that the packet should be handled by a 
5 specific protocol, then processing circuits 50 determine in a step 1 72 which protocol (e.g., 
CMXD, UDSCP, MDBP, DPP) is appropriate for handling the content of the packet. If a 
response is produced by processing unit 30 under the selected protocol or by the main MCMP 
protocol, as determined in an inquiry 1 74, that response is tranenutted in a step 176 to the 
client that originally made the request. If there was a service handofF, that is, if the packet was 

10 shunted to the host server, then the response will be transmitted to a computer other than the 
computer from which the host received the packet. In a step 178, processing unit 30 begins 
processing the next packet in the queue or waits for a new packet to arrive. 

As shown in Fig. 5, processing operation 173 includes an initial inquiry 116 into the 
type of packet. If the packet is an encr\'ption packet, encryptionldecryption unit 38 or 60 is 

1 5 activated in a step 1 1 8 to decrypt the packet using the appropriate decryption module or key. 
In a subsequent step 120, the packet encased in the data area of the encrypted packet is flagged 
as non-shuntable and placed back into the MCMP incoming packet queue. If it is determined at 
inquiry 116 that the packet is not an encryption packet, an MCMP status report indicated an 
unknown packet type is issue in a step 122 and the packet is discarded. The functionality of 

20 the MCMP protocol may be enhanced at a later time by enhancing the process illustrated in 
Fig. 5 to include conditions for additional types of packets. 

The Code Module Exchange Protocol (CMXP) handles dynamic downloading of 
executable code, program version control client-to-client module exchange, virus and 
malicious program protection, data uploading, idle-time downloading, and code module 
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caching. These functions are variously performed in servers 14 and 22 by code module 
exchanger 40 and version detector 42 and in user computer 12 by code module exchanger 56, 
author identification comparator 66, and unidirectional data submission and collection circuit 
86, as well as by various nondesignated generic processing circuits 50 and 70. The server-side 
5 portion of the CMXP protocol, as implemented in part by code module exchanger 40, handles 
the delivery of code modules and supporting resources such as graphic images and fonts. 
Requests to the CMXP server and to code module exchanger 40 can reference a file, a portion 
of a file (such as a code module), or a portion of a code module or other supporting module. 
Because programs are broken down into separate code modules, these code modules can be 
10 delivered on an as-needed basis, eliminating the need to download an entire program before 
execution thereof can commence. 

There are several ways of accommodating or incorporating an upgrade where programs 
are delivered piecemeal, module by module. If the old and new versions are completely 
compatible (for example, the new version was generated as the result a fix to a typographical 
15 error in a dialog box), the new modules can be merged with the old modules. Version 

information is stored on a per-file basis as well as a per-code-module basis. This means that 
code modules which were not changed in a version upgrade do not need to be downloaded 
again. If the old and the new versions are not compatible and cannot be merged, and the entire 
program has been cached locally or is still available from the server, the old version of the 
20 program can continue to execute until the next time the program is restarted. If the old and the 
new versions are not compatible and cannot be merged, and the old version of the program is 
no longer available in its entirety, the program should be immediately terminated and restarted 
using the new version code modules. The author of a program can override any of these 
update procedures by including a custom update module in the new version of the program,. 
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This code module is downloaded (if necessary) and executed whenever a version conflict 
arises. Then, an election can be made to perform any of the above procedures or a custom 
procedure such as remapping the contents of the program's memory area so that they can be 
used by the new version. 
5 Code modules and associated resources are cached by both user computers 12 and 

secondary servers 22. The caching rules can be incorporated into the CMXP protocol and/or 
the applications program itself This allows custom caching rules to be built into an 
application, thus providing for special caching schemes and hybrid applications. WTien a code 
module download is in progress, the number of bytes completed is stored in the cache along 
10 with the actual data downloaded. If a download is interrupted, it can resume where it left off 
at a later time. 

Fig. 7 illustrates operations executed by digital processing circuits of processing unit 30 
which are functionally modified in accordance with the CMXP protocol. The operations 
include a check on author identification. Generally, the author blacklist in memory area 68 of 

15 user computers 12 is transmitted to the user computers from a server which undertakes 
maintenance operations to keep the list updated (Fig. 8). 

As illustrated in Fig. 7, processing circuits 50 inquire at 180 whether an incoming 
packet constitutes a request for a resource. An affirmative answer to this inquiry leads to a 
further inquiry 182, as to whether the requested resource is available for anonymous access. If 

20 the resource is restricted, a determination 1 84 is made as to whether the requesting user has 
rights to access the requested resource. If the user has no such rights, an "access denied" 
message is returned to the requester in a step 1 86. If the requested resource is available to the 
requesting party, processing circuits 50 determine at a decision junction 188 whether the 
requested resource contains executable code. An affirmative determination causes a query 190 
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as to the validity of the author's fingerprint. If the fingerprint or author identification is invalid, 
a message is generated for a responsible party in a step 192. The local copy of the resource is 
deleted in a subsequent step 194 and a message "Resource Distribution Prohibited" is 
transmitted to the requesting pany in a step 196. 
5 If in response to query 190 it is found that the fingerprint of the author of the requested 

resource is valid, then a check 198 is made as to whether the author is blacklisted. A 
blacklisting leads to deletion of the local copy of the resource in step 194 and the issuance of 
the message "Resource Distribution Prohibited" in step 196. If the author is not blacklisted, or 
if the requested resource does not contain executable code, as determined at decision junction 
10 188, then the processing unit 30 queries at 200 whether the client already has an up-top-date 
copy of the resource. If the client or user already has the latest version of the resource, a 
message to that effect is transmitted in a step 202. If the client or user's copy of the resource 
is an older version, the requested resource is transmitted to the client in a step 204. 

If an incoming packet does not constitute a request for a resource, as ascertained in 
1 5 response to at inquiry 1 80, an investigation 206 is made as to whether the packet constitutes a 
request to modify a resource. If so, and if the resource is not available for anonymous 
modification, as determined at a decision junction 208, then processing unit 30 queries at 210 
whether the user has rights to modify the resource. If the user has no such rights, then a 
message "Access Denied" is returned to the requester in a step 212. If the resource is available 
20 for modification by anybody (decision junction 208) or by the particular user (querj' 2 1 0), the 
processing unit 30 makes the requested modification to the resource in a step 214 and notifies 
key secondary' servers, in a step 216, of the change to the resource. 

If an incoming packet does not constitute a request for a resource, as ascenained in 
response to inquiry 1 80, and is not a request to modif\' a resource, as determined in 
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investigation 206, then the processing unit 30 checks at 218 whether the packet is an update to 
a prohibition list, for example, a list of prohibited users or blacklisted authors. If the packet is 
such an update and is encrypted, as determined at decision junction 220, then the processing 
unit 30 determines at an inquiry 222 whether the packet was sent under the system user 
5 account. If so, the cached copy of the prohibition list is updated in a step 224 and all 

secondary servers are notified of the update in a step 226. If an incoming update request is not 
encrypted (decision junction 220) or is not sent under the system user account (inquiry 222), 
then an alert message is issued to an appropriate party in a step 228. In a step 230, a special 
status report is issued if an unknown packet type is received. 

10 In a CMXP maintenance loop, shown in Fig. 8, for updating a list of blacklisted 

authors, processing unit 30 asks in an initial query 232 asks whether the time since the last list 
update is more than a predetermined number of hours. If that much time has passed, an 
attempt 234 is made to contact the next server upstream of the server conducting the inquiry. 
If that ser\'er cannot be contacted, as determined in a scan 236, a check 238 is made as to 

15 whether there are other servers available. If another server is available, an attempt 240 is made 
to contact that server. If no server can be contacted, the time is again checked, at 242. If a 
predetermined interval has lapsed since the last update, then an alert is provided to an 
appropriate party in a step 244. 

If a server can be contacted, as ascenained in scan 236, the date of the last modification 

20 of the prohibition list is obtained from that server in a step 246. In a comparison 248, the 
processing unit 30 then determines whether the prohibition list has been modified since the list 
was cached by the processing unit. Where such a modification has occurred, a copy of the 
prohibition list is obtained in a step 250. The encryption status of the obtained list is 
investigated at 252. If the copy of the prohibition list. Finding a nonencrypted copy of the 
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prohibition list leads to an alert status in a step 254, while an encrypted packet is investigated 
at 256 to determine with the packet was sent under the system user account. A properly sent 
packet results in an update of the cached copy of the prohibition list in a step 258 and a 
notification of the update to all servers in a step 260. 
5 There are two primary methods for submitting or collecting data via the Uni- 

Directional Data Submission and Collection Protocol ("UDSCP"). Pursuant to the first 
method, submissions can be directed to either a primary server 14 or a secondary server 22. 
All submissions are then collected at a central server, where the submissions are processed by 
an application-specific server-side module. This method would be particularly useftil for 
10 collecting all form submissions on one server where they can be incorporated into a LAN- 
based mail system. In the second method, a submission can be again directed at either a 
primary server 14 or a secondary server 22. The submissions are collected on the servers to 
which they were originally submitted (or are shunted using the standard load collection rules). 
The submissions are then processed by an application-specific server-side module. This 
15 module could, for example, e-mail all of the submissions to an Internet e-mail address. 

Fig. 9 illustrates program steps undertaken by digital processing circuits of processing 
unit 30 which are fimctionally modified in in accordance with the UDSCP protocol. These 
circuit handle data submissions transmitted firom user computers 12, particulariy fi-om 
unidirectional data submission and collection circuit 90 of processing unit 54, and fi-om other 
20 servers. In a first inquiry 262, the processing unit 30 inquires whether an incoming packet is a 
data submission. If so, another inquiry 264 is made as to whether the data has to be collected 
immediately. If immediate collection is called for, the next question 266 entertained by the 
processing unit 30 is whether the data has to be collected at the source ser\'er. If not. the 
packet is passed in a step 268 through to a module that handles the final data collection. This 
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module handles e-mailing the submission, recording it in a database, writing it to a file, or 
preforming any other necessary server-side task with the data. Subsequently, in an 
investigation 270, it is checked whether the request has been processed by the data collection 
module. If so, the packet is removed in a step 272 from the UDSCP submission processing 
5 queue, assuming that is where the packet was obtained. Then a status report is issued at 274 
indicating successful data packet transmission. If investigation 270 reveals that the request has 
not been processed by the data collection module, the processing unit 30 questions at 276 
whether the failure to process was due to a possibly temporary condition. If the answer to this 
question 276 is negative, a status report 278 is issued describing the error condition. If the 

10 answer to the question 276 is affirmative, a status report 280 is issued describing the condition 
and indicating the possibility of delay in processing the data. The packet is then added in a step 
282 to the UDSCP processing queue. 

If an incoming packet is a data submission which does not have to be collected 
immediately, as determined at inquiries 262 and 264, a status report 284 is issued indicating 

1 5 success and the packet is then added in a step 286 to the UDSCP processing queue. If an 
incoming data packet is a data submission which has to be collected immediately at the source 
server, as determined at inquiries 262 and 264 and in response to question 266, a check 288 is 
made as to whether the host server is the source server. If so, the packet is passed in step 268 
through to a module that handles the final data collection. If not, processing unit 30 conducts 

20 an investigation 290 as to whether the source server can be contacted. If no contact is 

possible, a status report 292 is generated indicating that there will be a delay in processing the 
data and the packet is then added to the UDSCP processing queue in step 286. If the source 
server can be contacted, the data is transmitted to that server in a step 294. If the UDSCP 
ftinction-modified generic processing circuits of processing unit 30 are provided with a packet 
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other than a data submission, a report is produced in a step 296 indicated that the packet is of 
unknown type. 

Fig. 10 illustrates steps in a maintenance loop undertaken by generic distal processing 
circuits in processing unit 30 which are functionally modified in accordance with the UDSCP 
5 protocol. First, an inquiry 298 is made as to whether there are entries in the UDSCP 
submission processing queue. If so, the first entry is read in a step 300. Subsequently, 
processing unit 30 decides at junction 302 whether more than X seconds have passed since a 
date and time stamp on the entr>-. If not, the UDSCP submission processing queue is 
investigated at 304 to ascertain whether any further entries are in the queue. If so, the next 
10 entry is read in a step 306 and again the processing unit 30 decides at junction 302 whether 
more than X seconds have passed since a date and time stamp on the entry. If the time passed 
is greater than that predetermined limit, then a query 308 is made as to whether the server is 
too busy to handle the data submission. If the server is indeed too busy, processing unit 30 
questions at 3 10 whether the data has the be collected immediately If the data collection is 
1 5 not urgent, processing unit 30 determines at 3 1 2 whether the date and time stamp on the entry 
was earlier than a particular time. If the date and time stamp is recent, processing unit 30 
returns to investigation 304 to check any remaining data submissions in the UDSCP 
submission queue. 

If the server is not too busy to handle a data submission (query 308), if the data has to 
20 be collected immediately (question 3 1 0), or if data and time ^tamp indicates a certain age to the 
data submission (determination 312), processing unit 30 determines at a decision junction 314 
whether the data has to be collected by the source ser\'er. If not, the packet is passed in a step 
3 1 6 to a module that handles the final data collection. This module handles e-mailing the 
submission, recording it in a database, writing it to a file, or preforming any other necessary 
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server-side task with the data. Subsequently, processing unit 30 checks at 3 1 8 whether the 
data submission was processed by the data collection module. If processing has indeed 
occurred, the packet is removed from the UDSCP submission processing queue in a step 320 
and the processor 30 returns to investigation 304 to ascenain whether any further entries are in 
5 the queue. If the data submission packet has not been processed, which is discovered at 3 18, 
an inquiry 322 is made as to whether the failure to process the request is due to a possibly 
temporary condition. If not, a notification 324 is generated for alerting an appropriate person 
as to the failure. If so, the date and time stamp on the data submission is updated in a step 
326. 

10 If processing unit 30 determines at decision junction 3 14 that the data has to be 

collected by the source server and further determines at a subsequent decision junction 328 
that the host (itself) is the source server, then the packet is processed (step 316). 
Alternatively, if the source server must do the data collection and is a different computer, as 
determined at decision junction 328, then an attempt 330 is made to contact the source server. 

1 5 If the source server cannot be contacted, the date and time stamp on the data submission is 
updated in step 326. If the source server is available, the data submission is transmitted to the 
source ser\'er in a step 332 and the packet is removed from the UDSCP processing queue in a 
step 334. 

As discussed above, the MCMP protocol handles Load Distribution, User 
20 Authentication, and Encryption. All other functions are handled by sub-protocols. The MCMP 
protocol has four sub-protocols. These are the Code Module Exchange Protocol (CMXP), the 
Uni-directional Data Submission and Collection Protocol (UDSCP), the Metered Deliver)' and 
Billing Protocol (MDBP), and the Distributed Processing Protocol (DPP). This set of 
protocols can be expanded in the future to add additional functionality to the MCMP protocol. 
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Basic MCMP Packet Structure 

All MCMP packets consist of a MCMP header, followed optionally by one or more 
resource identifiers, and a data area called the packet body (Fig 1). The entire size of an 
MCMP packet can be calculated as 128+RsrcIDLen+PacketSize, where RsrcIDLen and 
5 PacketSize are elements of MCMP header (see below). 

The MCMP header identifies the sub-protocol to which the packet belongs, as well as 
the type of packet. In addition, the MCMP header contains load distribution, user 
authentication, and encryption information. The Resource identifiers identify any resource or 
resources referred to in the packet (the ResourceReq flag being set). The MCMP packet body 
1 0 contains packet-type specific information and is always interpreted by a subprotocol handle. 
The packet body is optional and can be omitted b ysetting the PacketSize element of the 
MCMP headet to be 0. 

The MCMP header structure is defined as: 



15 



20 



MCMPHeader,128 
MPVersion,4 
Proto Vendor, 8 
ProtoID, 8 
ProtoVer, 4 
TransID, 2 
PacketType, 2 
Packet Version, 4 
PacketSize. 4 
OriglP, 4 
OrigPort, 2 



$S MCMP header structure 

SS Master protocol version 

$$ Protocol vendor 

$$ Protocol ID 

$$ Protocol version 

SS Client Assigned Transaction-ID 

SS Protocol-specific Packet Type 

SS Packet version number 

SS Size, in bytes, of packet body 

SS Originating Host IP Address 

SS originating Host Port Number 
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UserID,10 

Password, 10 

RsrcIDLen,2 

RsrcIDs,2 

RsrcSrcIP,4 

Flags, 2 

,64 



$$ User ID for client authentication 

$$ Password for client authentication 

$$ Resource identifier length 

$$ Number of resource identifiers 

$$ Resource source IP 

$$ Flags; see functions below 

$$ Reserved 



10 



* Flags: 

Shunted = bit (FlagsJ) 
Shuntable = bit (Flags,2) 
Encrypted = bit (Flags,3) 
ResourceReq = bit (Flags,4) 



$$ Packet has been shunted 

$$ Packet can be shunted 

$$ Packet was encased in an encryption packet 

$$ Packet constitutes a request for a resource 



The elements of this structure are described in more detail below. 
15 MPVersion: This is a 4-character version identifier for the Master Protocol If the 

structure of the MCMP header or any other major component of the Master Protocol structure 
is revised, this version number is incremented. 

Proto Vendor: This is an 8-byte text literal that describes the software vendor initial 
responsible for maintaining the sub-protocol specificiation for the sub-protocol to which the 
20 packet belongs. 

ProtoID: This is an 8-byte text hteral assigned by the software vendor specified in the 
ProtoVendor element. This identifies the sub-protocol to which the packet belongs. The 
combination of ProtoVendor and ProtoID uniquely identifies a sub-protocol. 
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ProtoVer: This is a 4-byte text string that specifies the version of the sub-protocol 
specified in the ProtoVendor and ProtoID elements. The first to characters are the major 
version, the second two the minor version. All characters must be used, so if the major version 
is one character long, it must be written as 01, not 1 . This value does not contain a decimal 
5 point. For example, version 2.4 would be 0 2 4 0. 

Packet-Type Identifier (PacketType): A two-byte integer assigned by the vendor that 
uniquely identifies the packet type within a particular sub-protocol. 

PacketVersion: This is a 4-character identifier for the packet version. When the 
structure of a packet is changed, this version number is incremented. This allows a 
10 sub-protocol handler running on an MCMP server to deal with both old and new packet 

structures, should a packet structure need to be altered. The format for the string is the same 
as the format of the ProtoVer element of the MCMP header. 

Shunted flag (Shunted): A flag indicating whether this packet has been shunted as the 
result of a service hand off. 
1 5 Shuntable flag (Shuntable); A flag indicating whether this packet can be shunted. This 

flag and the Shunted flag are mutually exclusive. 

Encrypted flag (Encrypted): A flag indicating whether the packet was encrypted. This 
flag is cleared when a packet is placed in the MCMP Server incoming packets queue, unless 
the packet is place there by the decryption system, in which case the flag is set. 
20 Request-Resource flag (ResourceReq): Indicates whether the packet constitutes a 

request for a resource. 

Number of Resource Identifiers (RsrcIDs): Dpecifies the number of resource identifiers 
following the MCMP header structure. 

Resource Identifier Length (RsrcIdLen): Specifies the combined length of all resource 
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identifiers following the MCMP Header structure. 

Originating Host Address (OriglP, OrigPort) : This is the EP address of the host from 
which the request originated. If the packet was shunted, this is the IP address of the host that 
originally transmitted the request, not the address of the server that forwarded the request. 
5 Resource Source IP (RsrcSourcelP): This is the IP address of the host on which the 

original copy of the requested resource resides, if the Request-Resource flag is true. 

Cached Copy Date/Time Stamp (CacheDate, CacheTime): This is the date and time 
stamp of the cached copy of the resource, or zero if no cached copy exists. If the date and 
time stamp of the resource match this date and time stamp, the resource content will not be 
10 returned. 

Size of packet body (PacketSize): The size (in bytes) of the packet body following the 
MCMP Header and (if present) the resource identifiers. 

User ID and Password for client authentication (UserlD, Password): A user ID and 
Password used to authenticate the client. The authority for a user's ID and Password is the 
15 Resource Source IP server. If a request is made to a secondary server for a 

password-protected resource, the secondary server must check with the primary (or source 
server) for password authentication. This information can be cached for the duration of the 
session. 

Transaction ID (TransID); A unique ID assigned by the host initiating the transaction. 
20 This is used to track a transaction over one or more service hand-oflfs. For an encryption 
packet, this should be set to zero (although it can be set to a non-zero value in the encased 
packet). 

MCMP Resource Identifiers 

If the packet refers to one or more resources (the ResourceReq flag is set), the 
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Resource identifiers identify the resource or resources to which the packet refers. Resource 
identifiers are null-terminated text strings. The basic format for a resource identifier is: 
- type:[locator/s;]length[;date[,time]] 

Where: 

5 type Identifies the resource type; the possible values for this argument 

are sub-protocol-specific, 
iocator/s One or more values (in double-quotes if they contain commas; 

double up the double-quotes where they are used within the 
value) used to locate the resource. 
1 0 length The amount of the resource to read (in units specific to the 

sub-protocol). This is always the last item in the resource 
identifier. It can be in the format to specify n units starting 

at the beginning of the resource, the format to specify a 
range of units (inclusive), the format "/? //" to specify a starting 
15 unit and number of units, or to specify the entire resource. 

date The date, in the format mm/dd/yyyy that the cached copy of the 

resource was last modified. This field accepts both single and 
double digits for the month and day, although the year must be 
specified as a full 4-character string. Forward-slashes must be 
20 used as separators. 

Time The time, in the 24-hour format hh:mm:ss, that the cached copy 

of the resource was last modified, hh may be a single or double 
digit number, and mm and as must be double digit numbers (use 
a leading zero if necessary'). 
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The Resource ID is optional, and does not need to be included in a MCMP packet, so 
long as the ResourceReq flag is not set. 
Some example Resource ID's are: 

data:"\catharon\demos\media., "video.bin", "playSO";* 
5 prohibitedlist:* 
dir:"\";* 

data:"\catharon\demosV\"mag2.dat";0/256 
data:"\training","air.bin;\"Rudder";*; 10/03/1 995,4:03:30 
MCMP Packet Types 

10 The following subprotocols are not sub-protocl specific and are accordingly defined for 

the MCMP protocol: 

MCMP_Encrypt = h0002 $$ Encryption 

MCMP_Status = h0003 $S Status Report 

MCMP_PerfStatReq = h0006 $S Performance Statistics Request 

1 5 MCMP_PerfStatResp = h0007 $$ Performance Statistics 

Response 

MCMP^UserlReq = hOO08 $$ User Information Request 

MCMP_UserIResp = h0009 $$ User Information Response 

MCMP_EchoReq = hOOOa $$ Echo Request 

20 MCMP^EchoResp = hOOOb $$ Echo Response 

These packet types are described in detail below. 

ENCRYPTION (MCMP_Encrypt): The encryption packet is used when data must be 
encrypted. A packet to be encr>'pted is encased in the data area of a MCMP System 
encrj'ption packet. The MCMP Header for the encryption packet is: 

BNSCXJCtD; <WO 9907007A2_L> 



y/O 99/07007 



PCT/US98/15627 



48 



10 



PacketType: MCMP_Encrypt (hO002) 

PacketSize: Size of encased packet in encrypted form plus 32 bytes 

ResourcelD's: None 
Shuntable: Inherited from encased packet 

ResourceReq: False 
The packet body of the encryption packet is: 

Bytes 0-3 1 Encryption header 

Bytes 32-end Encrypted packet 

The header for the encryption packet is: 
PT_Encrypt_Header, 3 2 
DecryptLess,8 
DecryptUnit,8 
EncodingMethod,2 
,14 



$$ Code module to handle decryption 

$$ Encoding method 
$$ Reserved 



1 5 STATUS REPORT (MCMP^Status): The status report packet is used to return the 

status of an operation. When used, it is always a response to a previously transmitted request. 
The status packet contains detailed error information, including an English language 
description of the error or status value which can be displayed by the application if it cannot 
interpret the error code, 

20 A status report packet body consists of one or more information fields, which can vary 

in length. The first information field is always a Status Report Header. Each information field 
consists of an 8-byte header which indicates the length and type of the information field, 
followed by the field itself 

The MCMP Header for the status report packet is: 
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PacketType: MCMP_Status (hO002) 

PacketSize: Variable 
ResourceID*s: None 
Shuntable: No 
5 ResourceReq: No 

The Information Field Header for the status repon packet is: 
MCMP_StRprt IFldHdr,8 

IfldSize,2 $$ Size of information field 

IfldClass, 1 $$ Field alass ( 1 =Standard, 2=Protocol Specific) 

10 • IfldType,2 $$ Field type 

, 3 $$ Reserved 

Following are the standard information field types (where IFldClass=l): 
MSR_Header = 1 $$ Header 

MSR_ShortDesc - =2 $$ Short Description 

15 MSRLongDesc =3 $$ Long Description 

MSR_DetailDesc =4 $$ Detailed Description (Technical) 

MSR_XErr70 = 102 $$ LAS 7.0 Execution Error Data 

MSR_XErr70do - 103 $$ LAS 7.0 Execution Error-do-stack 

These information field types are described in detail below: 
20 The generic status report header (MSR_Header) is always present in all status report 

packets, and is always the very first information field in the packet. It has the following 
structure: 

MSR Header_Struc,32 

Proto Vendor, 8 $$ The Vendor of the protocol reponing the error 
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15 



ProtoID, 8 
ProtoVer, 4 
Severity, 1 



$$ The ID of the protocol reporting the error 
$$ The version of the protocol reporting the error 
$$ severity of error: 

-1 = Notification of success 

0 = Warning (operation will proceed anyway, 
but there may be a problem) 

1 = Error (operation cannot proceed) 

2 = Unexpected error 
S$ Protocol-specific error-flag. 
S$ Sub-Protocol-Specific error type 
SS Sub-Protocol -Specific error code 
$$ Reserved 

If the ProtoSpecific flag is set. then ErrorType and ErrorCode are protocol-specific. 
Otherwise, ErrorType is one of the following: 



ProtoSpecific, 1 
ErrorType, 2 
ErrorCode , 2 

,6 



ERRT _ Zretum 
*zretum* error 

ERRT^XErr 
ERRT_CErr 
ERRT Dosdata 



= 1 S$ 



= ? 



20 



S$ TenCORE Execution error 
SS TenCORE Condense error 
= 4 SS Catharon dosdata-style error 
For anything in the MCMP_Status packet that is protocol specific, the ProtoVendor 
and ProtoID from the Status Report Header are used to identify the protocol. 

The Short Description information field type (MSR_ShortDesc) is a shon description 
of the error, 40 characters long or shoner, that can be used in a list or wherever a brief, 
friendly error description is needed. This packet is 40 bytes long, and is structured as follows: 
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MSR_ShortDesc strtlc, 40 

ShortErTDesc,40 $$ Short description of error 

The Long Description information field type (MSR_LongDesc) is a longer description 
of the error, which can vary in length up to 2048 characters. This description can span 
5 multiple lines, with each line terminated by a carriage return (hOd). The length of this 
description is determined by the length of the information field, and the entire content of the 
information field is one long buffer variable containing the description as text. There is no 
maximum length to a line, and lines may be word-wrapped at any position when this 
description is displayed. 
10 The Detailed Description information field type (MSR_DetailDesc) is a detailed 

technical description of the error, with all diagnostic error information included. For example, 
this might be a standard TenCORE execution error as it would be written to the catharon.err 
log file by the Catharon error handler. This can var>' in length, up to 4096 characters. The 
description can span multiple lines, with each line terminated by a carriage return (hOd). Lines 
15 must be no longer than 80 characters. Lines longer than 80 characters may be truncated at 
display time. This description is never word-wrapped, and is always displayed in a fixed pitch 
font, allowing items on separate lines to be aligned and formatted using spaces (tables could be 
created using this method). The length of this description is determined by the length of the 
information field, and the entire content of the information field is one long buffer variable 
20 containing the description as text. 

The TenCORE 7 .0 Execution Error Data (MSR_XErr70) is an exact snapshot of the 
data generated by a TenCORE execution error, and returned by TenCORE in the execution 
error memory block. It is 256 bytes long. This information field type is normally only included 
if the error being reported is a TenCORE execution error. 
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The TenCORE 7.0 Execution Error To- Stack (MSR_XErr70do) is an exact snapshot 
of the TenCORE execution error -do- stack. The size of the data varies based on the size of 
the TenCORE -do- stack at the time of the error. 

PERFORMANCE STATISTICS REQUEST (MCMP^PerfStatReq): The performance 
5 statistics request packet requests a server*s current performance and load statistics. 
The MCMP Header of a performance statistics request is: 
PacketType: MCMP_PerfStatReq (hOOOS) 

PacketSize: 0 
ResourcelD's: None 
10 Shuntable: No (because this is a request for the statistics for the 

server to which it is addressed, shunting me packet 
would cause meaningless results) 
The response to this packet should be either an MCMP_PerfStatResp or a 
MCMP_.Status packet. 

1 5 PERFORMANCE STATISTICS REPORT (MCMP_PertStatResp): This packet is a 

response to an MCMP^PerfStatReq packet and contains a performance statistics report for the 
server to which it was addressed. 

The MCMP Header of a performance statistics report is: 

PacketType: MCMP_PerfStatReq (h0006) 

20 PacketSize: 32 

ResourcelD's: None 
Shuntable: No 
ResourceReq: No 
The Packet Body of a performance statistics report is: 
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10 



15 



PerfStats,32 

Pusage, 1 
CurReqs,2 
TotalRegs,2 
ShuntRegs,2 



$$ Processor usage (percent) 
$$ Current number of requests being processed 
$$ Total number of requests the can be processed 
$$ Threshold, in requests, at which shunting 
begins 

$$ Total physical memory on system 
$$ Used memory on system 
SS Total vinual memory on system 
$$ Used virtual memory on system 
S$ Current method for processing additional 

requests 
$S Resen/ed 

The elements of the packet body structure are, in detail: 

PUsage: Current processor usage percentage (0% to 100%). Set to -1 if processor 
usage percentage is not available. 

CurReqs: Approximate number of requests currently being processed. 
TotalReqs: Total number of requests that can be processed at one time. 
ShuntReqs: Maximum number of requests before shunting occurs. This is usually less 
20 than TotalReqsto allow some extra system resources for the purpose of shunting requests. 

PmemTotal: Number of b>ies of physical memory on server, or -1 if amount not 

known. 

PnemUsed: Number of bvies of physical memor\' that have been used, or -1 if amount 
not known. 



PmemTotal,4 
PmemUsed,4 
VmemTotal,4 
VmemUsed,4 
AreqPMethod,l 

,8 
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VmemTotal: Number of bytes of virtual memory available on server, -1 if not known. 

VmemUsed: Number of bytes of virtual memory in use, or -1 if not known. 

AreqPMethod: Method that will be used by the server deal with new incoming 
requests, based on the other statistics in this packet. This can have the numerical value 1, 2, or 
5 3.1 indicates that new requests will be processed normally; 2 indicates that new requests will 
be shunted; 3 indicates that new requests will be refused. 

USER AUTHENTICATION INFORMATION REQUEST (MCMP_UserIReq): This 
packet requests user authentication information on a particular user. This packet must be 
encn-pted, and is sent only from a secondary server to a primary server. The receiving server 
1 0 must check that the sender is listed as a secondary server before responding to this request. 

The expected response is either an MCMP_Status packet or an MCMP_UserIResp 

packet. 

This packet uses a special type of resource identifier, which is defined as follows: 



type:user[,uadbitem];length[:date,time] 



15 



Where: 



type 



Identifies the resource type; is always "useradb' 



It 



user 



The name of the user in question 



uadbitem 



Path to user authentication database item to retrieve. If omitted. 



a tree-file is resumed containing the entire user authentication 



20 



data tree for the specified user. The root of the resumed tree-file 



is equivalent to \LocalUsers\usemame in the user database file. 



length Portion of item to be resumed. 



Examples: 



useradb:JohnSACatharon\RAdmin\Rights;*:03/13/1995, 12:20:48 
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useradb:HugoC;* 

useradb:JDouglas,\XYZWidSt\WDBP\GroupMembership;256;S/12/1996, 01:00:30 
The User Authentication Database (UADB) is stored in a tree-file. User information is 
stored in \LocalUsers. Inside the \LocalUsers folder are folders for each user, named based on 
5 the user's ID. In each user's folder are folders for each vendor (i.e. "Catharon", "CTC". etc.), 
and inside the vendor folders are folders for each protocol defined by that vendor. The 
contents of a protocol folder are protocol-specific. The path specified in the resource ID is 
rooted at \LocalUsers\usemame. 

Basic user authentication information is stored in \Catharon\MCMP\BaseAuthData. 
1 0 This is structured as follows: 
UserAuthData,32 

UserlD, 1 0 S$ Userts name/ED 
UserPass, 1 0 $S User's password 
ExpTime,3 $S Time, in seconds, before data 
15 • S$ expires (10 to 864000). 

BinUID,4 S$ Binary User ID 
,5 $S Reserved 

If a secondary server sends a request in the form: 
useradb:usez,2ame;*[;date,time] 
20 the entire user authentication tree is retrieved for the specified user. The ability to read a 
specific item fi"om the user authentication tree is provided for future use and expandability. 

After retrieving user authentication data, that data can be cached for the period of time 
specified in the ExpTime element of the UserAuthData structure. The user authentication data 
may not be cached longer than the specified time. 
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The MCMP Header of the User Authentication Information Request is: 
PacketType: MCMP^UserlReq (hOOOS) 

PacketSize: 0 

ResourcelD's: One; specifying the user to retrieve information about, 

5 and what information to retrieve. 

Shuntable: No (must be processed by primary server because the 

primary server is the only authoritative source of 
information on the user). 
ResourceReq: Yes 
1 0 USER AUTHENTICATION INFORMATION RESPONSE (MCMP^UserlResp): 

The response to an MCMP_UserIReq packet, this packet contains the requested information in 
its data area. This data is either the raw data read from the requested data block in the user 
database, or (if uadbitem is omitted) is a tree file containing the entire user information tree for 
the specified user, with the root of the file being equivalent to \LocalUsers\username in the 
15 UADB. 

The MCMP Header of the User Authentication Information Response is: 
PacketType: MCMP^UserlResp (hO009) 

PacketSize: Variable 
ResourcelD's: None 
20 Shuntable: No 

ResourceReq: No 
ECHO REQUEST (MCMP_EchoReq): This packet is used to time the connection to a 
panicular MCMP host. When this packet is received by an MCMP host, a MCMlP_EchoResp 
packet is immediately sent back. The data area can contain any data, up to a maximum size of 
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2048 bytes. The return packet's data area will contain the same data. 
The MCMP Header of the Echo Request is: 

PacketType: MCMP^EchoReq (hOOOa) 

PacketSize: Any 
5 ResourcelD's: None 

Shuntable: No 
ResourceReq: No 
ECHO RESPONSE (MCMP_EchoResp): This packet is sent in response to an 
MCMP_EchoReq packet. 
10 The MCMP Header of the Echo Response is: 

PacketType: MCMP_EchoResp (hOOOb) 

PacketSize; Same as original MCMP_EchoReq packet 

ResourcelD's: None 
Shuntable: No 
15 ResourceReq: No 

Some files in a directory may support additional access pennission information. For 
example, a tree file could contain information on access permission for individual units within 
the tree file. 

CMXP Resource Identifiers 

20 Resource Identifiers for CMXP packets are defined as follows: 

type:patht,file[,unit]];length[;date,time] 

Where: 

type Identifies the resource type. This can be either "Data" to read data fi*om 
the specified resource, or "Dir" to read a director>' of contained 
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resources. 

path Path to a directory... must be at least a backslash "\". If file and unit are 
not specified, the directory is considered the resource to be read; 
otherwise, the file or unit referenced is assumed to be located in the 
specified directory. If file and unit are not specified, then type must be 
"Dir". 

file A filename. If unit is not specified, the file is considered the resource; 
otherwise, the unit is assumed to be located in the specified file. A file 
resource can be accessed with both the "Dir" and "Data" resource types; 
"Dir" will reference the list of contained units, while "Data" will 
reference the actual data contained in the file, 
unit A unit name. If specified, the unit is considered to be the resource. 
This can be accessed with both the "Dir" and "Data" resource types; 
"Dir" will reference the list of sub-units, while "Data" will access the 
data contained in the unit, 
length The portion of the resource to read. If typeis "Data", this value is in 
bytes. If type is "Dir", this value is in directory entries, 
date/time Can only be specified in a request packet. Causes the recipient process 
to ignore the request unless the resource has been modified since the 
date/time specified. This can be used in conjunction with the 
CMXP_ReadReq packet to request that a resource be sent only if it has 
changed since it was cached on the client. 

CMXP Packet Types 
The following is a list of the packet types used by the CMXP protocol at this time. Th 
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functionality of the CMXP protocol can be expanded in future by adding to this list of packet 
types. 

CMXP_ReadRsrcReq = h0002 

CMXP_ReadRsrcResp= h0003 
5 CMXP_WriteRsrc = h0004 

CMXP_CreateRsrc = hOOOS 

CMXP_DestroyRsrc = h0006 

CMXP^RenameRsrc = h0007 

CMXP_CopyRsrc = h0008 
10 CMXP^MoveRsrc = h0009 

CMXP_AltSListReq = hOOOa 

CMXP_AltSListResp = hOOOb 
These packet types are described in detail below. 

READ RESOURCE REQUEST (CmxP_ReadRsrcReq): This packet is a request to 
15 read one or more resources. It is sent from a client to a server to download a resource, sent 
from a client to a client to request a code module transfer for a plug-in module, or sent from a 
server to a server to request transfer of the appropriate resource to service a client request. A 
CMXP_ReadRsrcReq packet can request either resource content, resource information, or 
both. Because the definition of a resource includes file directory and code module directories, 
20 this packet can also be used to request a list of files in a directory or code modules in a file. 

This packet is responded to with a series of packets (one for each request resource). 
These packets are either CMXP^ReadRsrcResp (if the resource was successfiilly read) or 
MCMP_Status (if there was an error reading the resource). 

The MCMP Header of a read resource request packet is: 
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10 



PacketType: CMXP_ReadRsrcReq (honey) 

Packet Size: 32 

ResourceID*s: One or more, Identifying resources to read 

Shuntable: Yes 
ResourceReq: Yes 
The Packet Body of a read resource request packet is: 

ReadRsrcReqHeader,3 2 

RHFlags,2 $$ Flags 

,30 S$ Reserved 

* Flags: 

Includelnfo = bit(RHFlags,l) 
IncludeData - bit(RHFlags,2) 
IdlePreCache = bit(RHFlags,3) 



SS Include resource information 
S$ Include resource content 
SS Request is the result of an idle-time 
pre-caching operation. 

1 5 The elements of the packet body are, in detail: 

Includelnfo: If set, this flag causes infonnation about the resource to be returned. 

IncludeData: If set, this flag causes the resource content to be returned. 

IdlePreCache: If set, indicates the the request is the resuh of an idle-time pre-caching 
operation initiated by the chent without user involvement. A CMXP server processes packets 
20 with this flag clear before packets with this flag set are processed. When the load on a CMXP 
server becomes too high for it to deal with all requests, and it can not shunt requests, requests 
with this flag set will be dropped before requests with this flag clear. 

Includelnfo and IncludeData can both be set in the same request In this case, the 
response is the resource information followed by the resource content. This is the most 
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common request type. At least one of these flags must be set in each request packet 

READ RESOURCE RESPONSE (CMXP_ ReadRsrcResp): Sent in response to a 
CMXP_ReadRsrcReq packet, this packet contains the requested information. Note that this 
packet is never sent in response to a CMXP_ReadRsrcReq if an error condition exists; instead, 
5 a MCMP_Status packet is sent. 

Depending on the state of the Includelnfo and IncludeData flags in the 
CMXP_ReadRsrcReq packet, the packet body may contain resource information and/or 
resource content. The resource information, if it is present, always comes first in the packet 
body, followed by the resource content, if present. The size of the resource information can be 
10 determined by reading the ResourcelnfoSize element of the version of a program can be 
sucessfully merged with code modules from an old version of the program. 

RsMaxSubs: The maximum number of subsidiaries that the resource can contain. 

RaSizeAInfo ; The size, in bytes (1 to 8), of the associated information for the resource 
(RsAInfo). 

15 RsSizeSubName: The maximum length, in characters, of the name of a subsidiary of the 

resource. 

RsHeight, RsWidth: The height and width of the bounding rectangle of the resource at 
its defauh scaling, if applicable. This is used for object-based drawings, images, etc. 

RsPTime: The playing time, in seconds at the default playing speed, of the resource (if 
20 appliable); used for video clips, wav files, midi files, animations, etc. 

WRITE RESOURCE (CMXP^'riterSrc): This packet writes data to the specified 
resource. This requires sending a packet to the primar>' server that cannot be shunted, so this 
can increase server load. For form submissions and other uni-directional submissions, the 
UDSCP protocol is recommended over the write functions of the CMXP protocol. 
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A CMXP_WriteRsrc request may fail due to, among other things, the fact that the user 
is not allowed to write to the specified resource. This situation may be remediable by 
repeating the request with a user-id and password specified (in this case, the request must be 
encased in a MCMP^Encrypt packet). 
5 There are two variations of the status code returned when access is denied due to failed 

user authentication. One variation indicates that the client should prompt for a user name and 
password. This is a "hint" to the client that the resource may be accessible via a user name and 
password. It is not conclusive. In other words, the variation on the Access Denied code does 
NOT indicate whether access is really available to anyone; i just indicates whether the client 
1 0 should ask. There may, for example, be a resource designed to be accessed under program 
control, and not under user control which requires user authentication of an "automation 
user", and which denies access the rest of the time without even prompting for a 
user-id/password. 

The packet body contains the data to be written to the resource. 
1 5 The MCMP Headerof the write resource packet is: 

PacketType: CMXP_WriteRsrc (h0004) 

PacketSize: Variable 

ResourcelD's: One; the ID of the resource to-wnte to 

Shuntable: No 
20 ResourceReq: Yes 

CREATE RESOURCE (CMXP^CreateRsrc): This packet creates a subsidiary in the 
specified resource. This includes files, directories, and units. The same rules regarding user 
authentication apply to this packet as apply to the CMXP^WriteRsrc packet. 
The MCMP Header of the create resource packet is: 
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PacketType; CMXP^CreateRsrc (h0005) 

PacketSize: Variable 

ResourcelD's: One; the ID of the resource In which to create the new 

subsidiary. 

5 Shuntable: No 

ResourceReq: Yes 
The Packet Body of the create resource packet is: 
NewRsrc,300 

RsSize,4 $S Size, in bytes, of resource 

10 • RsAInfo,8 $$ Associated information (if applicable) 

RsMaxSubs,2 $S Maximum number of subsidiaries 

RsSizeAlnfo,! $$ Size, in bytes, of associated information 

RsSizeSubName,2 $$ Maximum length of a subsidiary's name 
RsName,256 $S Resource Name 

1 5 ' RsName2,8 $$ Secondar>' Resource Name 

RsType,8 $S Resource type 

,11 $$ Reserved 

The elements of the packet body are, in detail: 

ReSise: The size, in bytes, of the new resource. If creating a TenCORE nameset or 
20 daiaset, this must be a multiple of 256 bytes, and is equivalent to the records argumen of the 
-createn- command multiplied by 256 (to conven from records to bytes). When creating new 
directories, this is ignored. 

R-AInfo: Associated information for the resource, if applicable (see CMXP 
_CreaieRsrc above) 
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RsMaxSubs: The number of subsidiaries allowed in the resource, if applicable. This is 
required for TenCORE namesets, and is equivalent to the names argument of the -createn- 
command. In most cases, when not dealing with TenCORE namesets, this is ignored. 

R-SizeAInfo: The size of the resource's associated information. For namesets, this is 
5 equivalent to the infolength argument of the -createn- command. 

RsSizeSubName: Maximum length of a subsidiary's name. For TenCORE namesets, 
this is equivalent to the namelength argument of the -createn- command. In most cases 
when-not dealing with TenCORE namesets, this is ignored. 

ReName: The name of the resource to create. The length of this name and the rules for 
10 allowed characters depend on the type of resource being created. 

RaName2: This is a secondar>' name for the resource. It is not currently used, but is 
provided for future use. This may be used, for example, to specify a short file name alias to go 
with a long filename in Windows 95/NT. 

RaType: This specifies the type of resource being created. Note that not all resource 
1 5 types are necessarily valid for all possible resources in which they could be created (i.e., one 
cannot create a file inside of a unit). Where only one resource type is possible for a particular 
containing resource, the value 'default' is used (for example, the only type of resource that can 
be created inside a TenCORE nameset is a block). This value is an 8-byte text literal. 
The following resource types are currently defined for the CMXP protocol: 
20 course A course file (TenCORE nameset with .CRS extension) 

group A group file (TenCORE nameset with .GRP extension) 

nameset A gentral purpose nameset file (TenCORE nameset w-ith .NAM 
extension) 

roster A roster file (TenCORE nameset with ,RTR extension) 
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source 


A source file (TenCORE nameset with .SRC extension) 


studata 


A student data file (TenCORE nameset with .SDF extension) 


tpr 


A Producer file (TenCORE nameset with TPR extension) 


binary 


A binary file (TenCORE nameset with .BIN extension) 


file 


An operating system file 


dir 


An operating system folder or directory 


dataset 


A TenCORE dataset 


tree 


Catharon tree-file 


default 


The default type for the container 


block 


A data block (in a nameset or tree-file) 


folder 


A folder (in a time-file) 



DESTROY RESOURCE (CMXP_DestroyRsrc): This packet destroys the specified 
resource The same rules regarding user authentication apply to this packet as apply to the 
CMXP_WriteRsrc packet. The MCMP Header of this packet is: 
15 Packet Type: CMXP_DestroyRsrc (h0006) 

PacketSize: 0 

ResourcelD's: One; the ID of the resource to destroy 

Shuntable: No 

ResourceReq: Yes 
20 RENAME RESOURCE (CMXP_RenameRsrc): This packet renames the specified 

resource. The same rules regarding user authentication apply to this packet as apply to the 
CMXP_WriteRsrc packet. The packet body contains the new name for the resource. The 
MCMP Header of this packet is: 

Packet T>T)e: CMXP^RenameRsrc (hO007) 
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PacketSize: 272 

ResourcelD's: One; the ID of the resource to rename 

Shuntable: No 
ResourceReq: Yes 
5 The Packet Body of the rename resource packet is: 

RenameRsrc,272 

ResourceName,256 $$ New name for resource 

ResourceSecondaryName,8 $$ Secondary name for resource (if 

applicable) 

10 ,9 $S Reserved 

COPY RESOURCE (CMXP_CopyRsrc): This packet copies the specified resource. 
The same rules regarding user authentication apply to this packet as apply to the 
CMXP_WriteRsrc packet The MCMP Header of the copy resource packet is: 
PacketType: CNlXP_CopyRsrc (h0008) 

15 PacketSize: 0 

ResourcelD's: Two; the first is the location of the resource to copy, the 

second the location to create the new copy of the 
resource. 
Shuntable: No 
20 ResourceReq: Yes 

MOVE RESOURCE (CMXP_MoveRsrc): This packet moves the specified resource. 
The same rules regarding user authentication apply to this packet as apply to the 
CMXP^WriteRsrc packet. The MCMP Header of the move resource packet is: 
PacketType: CMXP_MoveRsrc (h0009) 
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Two; the first ts the old location of the resource, the 
second the new location for the resource. 



Shuntabte: No 
5 ResourceReq: Yes 

ALTERNATE SERVER LIST REQUEST (CMXP_AltSListReq): This packet 
requests a list of secondary servers available for the specified resource. The server should 
respond with an CMXP_ AltSListResp packet, except in the case of an error, in which case an 
MCMP^Status packet should be returned. The MCMP Header of this packet is: 
1 0 Packet Type: CMXP_AltSUstReq (hOOOa) 

PacketSize: 0 

ResourcelD's: One - The resource for which to list secondary servers. 

Shunt able: Yes 
ResourceReq: Yes 
1 5 ALTERNATE SERVER LIST RESPONSE (CMXP_AltSListResp): This packet is 

sent in response to an CMXP_ AltSListReq packet and contains the list of alternate servers. 
The MCMP Header is: 

Packet Type: CMXP_AltSUstResp (hOOOb) 

PacketSize: Variable 
20 ResourcelD's: None 

Shuntable: No 
ResourceReq: No 
The Packet Bodyof the CMXP_AltSListResp packet is: 
AltSList(nn),16 
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IP,4 $$ IP Address of server 

Port, 2 $$ Port on server to access 

Load, 1 $$ Last known load on server 
Ping,4 $$ Last known ping-time to server 

,4 $$ Reserved 

UDSCP Packet Types 
The foUov^ng is a list of the packet types used by the UDSCP protocol at this time. 
The functionality of the UDSCP protocol can be expanded in future by adding to this list of 
packet types. 
10 UDSCP_Submission = h0002 

UDSCP_QueueStatusReq = h0003 
UDSCP_QueueStatusResp = h0004 
These packet types are described in detail below. 

DATA SUBMISSION (LT)SCP_Submission): This is the primary packet type for the 
15 UDSCP protocol. It is generated by a client, and then foru'arded from server to server until it 
reaches the collection point. The packet body consists of a UDSCP Header followed by the 
content of the submission. 

The MCMP Header of the data submission packet is: 

PacketType: LTDSCP_Submission (hO002) 

20 PacketSize, 32 + Size of data being submitted 

None 
Yes 
No 



PacketSize, 
ResourcelDs: 
Shuntable: 
ResourceReq: 
The UDSCP Header is: 
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$$ Size of UDSCPSubmitHeader 

$$ Size of data being submitted 

S$ Collection method (l=Central, 2=Secondary) 

$$ Collection point IP Address 

$$ Priority (0=low, l=normal, 2=iirgent) 

$S TenCORE Lesson/Unit to process submission 

SS Flass 



UDSCPSubmitHeader,32 

HeaderSize,2 

DataSize,4 

Cmethod, 1 
5 • CpointIP,4 

Priority, 1 

Lesson, 8 

Unit,8 

Flags, 2 
10 • ,2 

* Flags: 

Forwarded = bit(Flags,l) SS Submission has been forwarded by a server 
The elements of the UDSCP header are described in detail below: 
HeaderSize: The size, in bytes, of the UDSCPSubmitHeader structure. This value 
1 5 should be read to determine the size of the whole structure, this allowing the structure to be 

expanded in future without affecting existing code. 

DataSize: The size, in b>ies, of the content of the submission following the UDSCP 

Header. 

Cmethod: The collection method to be used. This is an integer value. A setting of 1 
20 causes data to be collected and processed at a centeral server, while a setting of 2 allows data 
to be processed on secondar\' servers. 

CpointIP: The IP address of the collection point (centeral ser\'er). This is ignored if 
CMethod=2. 

Priority: The priority of the submission. This is an integer value, and can be either 0 for 
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low, 1 for nonnal, or 2 for high priority. UDSCP servers attempt to process high priority 
submissions immediately, while normal and low priority submissions are held in the UDSCP 
submission queue and processed when the server would othewise be idle. If a normal or low 
priority remains in the UDSCP queue for longer than the user configurable time limit, the 
5 server will attempt to process it immediately regardless of load or, failing to do so, notify a 
responsible person. The time limits for low and normal priority submissions are configurable 
separately, and low priority submissions are usually configured for a longer timeout. 

Lesson, Unit: The names of the TenCORE lesson and unit that will process the 
submission. 

10 Forwarded: This flag is set if the submission has been forwarded by a UDSCP server, 

or clear if this is the first UDSCP server to deal with the submission (i.e., the submission came 
from a client). 

QUEUE STATUS REQUEST (UDSCP_ QueueStatusReq): This packet requests the 
status of the UDSCP queue. The expected response is either an MCN4P_Status packet or a 
1 5 UDSCP QueueStatusResp packet 

The MCMP Headerof the queue status request packet is: 

Packet Type: UDSCP _ Queue Status Req (h0003) 

PacketSize: 0 
ResourcelD's: None 
20 Shuntable: No 

ResourceReq: No 
QUEUE STATUS RESPONSE (UDSCP:QueueStatusResp): This packet is the 
response to a UDSCP_QueueStatusReq packet. It contains infonnation about the UDSCP 
ser\'er's current UDSCP queue status. The MCMP Header is: 
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10 



15 



PacketType: UDSCPQueueStatusResp (h0004) 

Pack^tSize: 0 
ResourcelD's: None 
Shuntable: No 
ResourceReq: No 
The Packet Body of this status response packet is: 
QueueStatus,64 

Entries,4 

LowEntAge,4 



HighEntAge,4 

AvgEntAge,4 

HighPriEnt,4 

LowPriEnt,4 

FwdEnt,4 

ToFwdEnt,4 



,32 



$$ Total number of entries in the queue 
$S Age of the newest entry in the queue, in 
seconds 

SS Age of the oldest entry in the queue 

$S Age of the average queue entry 

$S Number of high-priority entries in the queue 

SS Number of low-priority entries in the queue 

SS Number of entries which have been forwarded 

SS Number of entries which must be forwarded 

$$ Reser\'ed 



The Metered Delivery and Billing Protocol (MDBP) controls access to pay-for content, 
including delivering credit to pay for the content, and collecting royalty information after the 
20 content has been purchased. 

MDBP Packet Types 
The MDBP protocol works closely with the CMXP protocol. The CMXP protocol is 
used to deliver the content in encrypted form. The content is then decrypted when it is 
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unlocked by the MDBP libraries on the client machine. The content is unlocked when it is paid 
for with credit on the local machine. Credit can be replenished through the MDBP protocol. 

When credit is replenished on the local machine, the royalty information is reported to 
the credit server, which then handles the appropriate distribution of profits. 
5 In a standard credit-purchasing transaction, three packets are exchanged: 

An MDBP_CreditReq is sent from the client to the server 
The server responds with an MDBP_CreditTransfer 
The client sends an MDBP_PurchaseReport to the server 
Before credit can be purchased by a user, that user must be registered with the credit 

1 0 server. 

The following is a list of the packet types used by the MDMP protocol at this time. 
The functionality of the MDBP protocol can be expanded in fliture by adding to this list of 
packet types. 



MDBP_CreditReq 


= 2 


$$ Request for additional credit 


1 5 MDBP^CreditTransfer 


— J 


$S Response to MDBP^CreditReq 


MDBP^RegisterUser 


= 4 


S$ Register a user 


MDBP^RegisterliserResp 


= 5 


S$ Response to MDBP_RegisterUser 


MDBP^WriteUserData 


= 6 


S$ Write user data 


MDBP_ReadUserDaia 


= 7 


$$ Read user data 


20 MDBP_ReadUserDataResp 


= 8 


S$ Response to MDBP_ReadUserData 


MDBP_PurchaseReport 


= 9 


SS Puchasing/Royalty Report 


The MDBP packet types are 


described in detail below. 



REQUEST FOR ADDITIONAL CREDIT (MDBP_ CreditReq): This packet requests 
additional credit from the server. The packet body contains the user's ID code, which is used to 
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access the user's data in the user database, as well as the amount of credit to be purchased. The 
user's data includes a billing method to use to pay for the credit. This packet must be 
encrypted. The expected response is either an MDBP_CreditResp or an MCMP_Status packet. 
The MCMP Header of a credit request packet is: 
5 Packet Type: MDBP_CreditReq (h0002) 

PacketSize: 22 
ResourcelD's : None 
Shuntable: No 
ResourceReq: No 
10 The Packet Bodyof a credit request packet is: 

UserID,8 $$ User ID; B-byte integer value 

Password, 1 0 S$ User' 8 pasaword 

Credit, 4,r S$ How much credit to purchase (in dollars) 

CREDIT TRANSFER (NlDBP^CreditTransfer): This packet is the response to an 
15 MDBP_CreditReq. It actually performs the transfer of credit from the server to the client. The 
packet body contains information on the credit transfer. This packet must be encrypted. 
The MCMP Header of a credit transfer packet is: 

PacketType: MDBP_CreditReq thOoOS) 

PacketSize: 20 
20 ResourcelD's: None 

Shuntable: No 
ResourceReq: No 
The Packet Body of a credit transfer packet is: 

UserID,8 SS The ID of the user who should be receiving this credit 

BNSDOCID: <W0 9907007A2 I > 



wo 99/07007 



PCT/US98/1S627 



74 



Credit, 4,r $$ The amount of credit purchased (in dollars) 

Tserial,8 $$ A serial number used to track the transaction 

USER REGISTRATION (MDBP_RegisterUser): This packet is used for the initial 
registration of a user with a credit server. It causes a new emry to be created in the user 
5 registration database. The packet body contains information about the user which will be 
written into the standard fields in the user's new record. The information can be read and 
modified at a later time through use of the MDBP_WriteUserData and MDBP_ReadUserData 
packets. This packet must be encrypted. The expected response to this packet is an 
MDBP_RegisterUserResp or MCN-IP.Status packet. 
1 0 The MCMP Header of a user registration packet is. 

PacketType. MDBP_RegisterUser (hO004) 



15 



20 



PacketSize: 
ResourcelD's: 
Shuntable. 
ResourceReq. 



None 

No 

No 



The Packet Bodyof a user registration packet is. 
RegisterUser, 512 



Name, 54 


S$ Full name 


Company, 54 


SS Company name 


Addressl45 


SS Line 1 of the street address 


Address2,45 


$$ Line 2 of the street address 


City, 20 


$S City name 


State,2 


$$ 2-letter state abbreviation 


Pcode,16 


SS Postal code (zip code) 
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Country,30 
Telephone, 16 
AX,16 
Email, 100 
CardNo,20 
CardExpDate,5 

Password, 10 
,79 
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$$ Country name 
$$ Telephone number 
$$ FAX number 
$$ E-mail address 

$$ Credit card number ('nnnn nnnn nnnn nnnn') 
$$ Credit card expiration date (*mm/yy' or 'mm- 

yy') 

$S Password 
S$ Reserved 



10 USER REGISTRATION RESPONSE (MDBP_RegisterUserResp): This packet is the 

response to an MDBP_RegisterUser packet. It acknowledges the fact that the user has been 
registered, and returns the user's assigned ID code. The MCMP Header of this packet is: 
Packet Type : MDBP_RegisterUserResp (hOOOS) 

8 

1 5 ResourcelD's: None 

No 
No 



20 



PacketSize: 
ResourcelD's: 
Shuntable: 
ResourceReq: 
The Packet Body is: 

userID,8 SS user ID, 8-b>te integer value 

WTUTE USER DATA (MDBP WriteUserData): This packet writes data to the user 
database. This uses a resource identifier to identify the element in the user registration 
database to write to. The packet body is the data to be written. This packet uses a special 
type of resource identifier, which is defined as follows: 
type userid[,dbitem];length[;date,time] 
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Where: 



type Identifies the resource type; is always "mdbpuser" 

userid The ID of the user in question (in hexadecimal) 

dbitem Path to user database item to retrieve. If omitted, a tree-file is 

5 resumed containing the entire user data tree for the specified 

user. 

length Portion of item to be returned. 

Examples: 

mdbpuser:00000000000003e4ACatharon\RAdmin\Rights;*;03/13/1995,12:20:48 

10 mdbpuser:0000000000000014;* 

mdbpuser:0000000000002afi\XYZWidgt\\\T)BP\GroupMembership;256; 

5/12/1996,01:00:30 

The user database contains a system folder and a publishers folder. The system folder 
contains the data specified in the initial User Registration packet, and can be expanded to 
1 5 contain additional data. The publishers folder contains a subfolder for each publisher, named 
based on the publisher's name, and the publisher's folder contain, in turn, publication folders, 
named based on the publication. The organization of data within a publication folder is specific 
to the publication. 

The MCMP Header of the write user data packet is: 
20 PacketType: MDBP_WriteUserData (h0006) 

PacketSize: Variable 
ResourcelD's: 1 (The resource to write to) 

Shuntable: No 
ResourceReq: Yes 
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5 



10 



READ USER DATA (MDBP_ReadUserData): This packet reads data from the user 
database. This uses a resource identifier to identify the element in the user registration 
database to read from. The format of the resource identifier is the same as that for the 
resource identifier used in the MDBP^WnteUserData packet. 

Muhiple resource identifiers can be specified, causing each of the specified elements in 
the user registration database to be returned. 

This packet is responded to with a series of packets (one for each request resource). 
These packets are either MDBP_ReadUserDataResp (if the resource was successfiilly read) or 
MCMP_Status (if there was an error reading the resource). 

The MCMP Header of the read user data packet is: 

Packet Type: MDBP_ReadUserData (hOO07) 

PacketSize: 0 

ResourcelD's: 1 or more 

Shuntable: No 

ResourceReq: Yes 

READ USER DATA RESPONSE (MDBP_ReadUserDataResp): This packet is the 
response to an MDBP_ReadUserData packet. It contains the content of the requested element 
of the user registration database. The body is the data that was read. The MCMP Header is: 



PacketType: 



MDBP_ReadUserDataResp (h0008) 



PacketSize: 



Variable 



ResourcelD's: 



None 



Shuntable: 



No 



ResourceReq: 



No 



PURCHASING/ROYALTY 



REPORT (MDBP„PurchaseRepon): One or more of 



RNSnonin' <WO 9907007A2 I > 



wo 99/07007 



PCT/US98yi5627 



10 



78 

these packets is sent from the client to the server after the client has received a response to an 
MDBP_CreditReq packet, if the client has purchasing or royalty information to report. 

The data area contains a generic royalty report header followed by a 
publication-specific royalty-report data area. In some cases, the royalty report header is 
5 sufficient to report the needed royalty information, so the data area is optional and does not 
have to be included. Any data following the royahy report header is assumed to be 
publication-specific data. 

The MCMP Header of the royalty report packet is: 

PacketType: MDBP_PurchaseReport (h0009) 

PacketSize: Variable 
ResourceiD's: None 
Shuntable: No 
ResourceReq: No 
The Royalty Report Header is 
RoyaltyReport,128 
HeaderSize,2 
Publisher,45 
Publication,45 
Vollssue,20 

Version, 4 
UserlD,8 
CreditSpent,4,r 



15 



20 



SS Size, in bytes, of royalty report header 
SS Name of publisher 
S$ Name of publication 

SS Volume and/or issue number of publication, if 

applicable 
SS Version of publication, if applicable 
SS ID of user who was reading this publication 
SS Credit spent, in dollars, on this publication 



DPP Packet Types 
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The distributed processing protocol (DPP) is used to reduce the processing load 
created by a particular task by distributing it over multiple computers. The protocol is used to 
search for and locate idle systems and (in conjunction with the CMXP protocol) transmit the 
appropriate code modules to those systems so that they can assist with the task. When the task 
5 is complete, the protocol is used to gather the results from all of the "assisting" machines and 
collect them and compile them on the machine that initiated the task. 

The functionality provided by this protocol should not be confused with the load 
distribution functionality provided by the main MCMP protocol. The MCMP protocol's load 
distribution works by distributing client requests over various machines in various locations. 
1 0 The DPP protocol uses several machines working together to accomplish a single task, and is 
more suited to a local area network, and to processor intensive tasks, such as rendering of 3D 
images. 

Each system involved in the distributed processing process must be configured with a 
list of those systems which can assist it with a task, as well as those systems which it can assist 

15 with tasks. This list can include entries with wildcards, to specify an entire network, such as 
192.168.123.* for the entire 192.168.123. C-level network. 

The purpose for this system configuration is to control who can utilize a system's 
processor. For example, a company might want to limit shared processing to systems within 
it's own internal network, for security reasons. 

20 Systems can also be assigned priorities for access to a computer's processor. For 

example, a company may want all of it's computer to grant distributed processing requests 
fi-om other computers on it's network in preference to other requests. However, if that 
company is affiliated with some other company, it might want to grant that other company 
access to it's computers for distributed processing purposes, provided that none of it's own 
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computers require processing assistance. 

The following is a list of the packet types used by the DPP protocol at this time. The 
functionality of the DPP protocol can be expanded in future by adding to this list of packet 
types. 

5 DPP_AssistReq =2 $$ Request for processing assistance 

DPP_AssistResp =3 $$ Response to DPP_AssistReq 

DPP EndTaskReq =4 $$ Request to terminate processing assistance 

DPP EndTaskNotify = 5 S$ Notification of termination of assistance 

DPP_UpdateReq =6 $S Request for update of task status 

10 DPP_UpdateResp =7 SS Response to UpdateReq 

These packet types are described in detail below. 

REQUEST FOR PROCESSING .ASSISTANCE (DPP.AssistReq): This packet is sent 
by a system requiring processing assistance to another system to request processing assistance 
from that system. This packet comains all the information needed to initiate a distributed 
1 5 process, including the resource identifier for the initial code module to handle the process, so 
that the code module can be fetched via CMXP if necessary. The response to this packet is 
either a DPP_AssistResp packet (if the recipiem system can assist) or an MCMP Status packet 
(if the recipient system can not assist). 

Possible reasons for an MCMP_Status packet can include: 
20 • Access Denied 

The system to which the packet was sent was not allowed to assist with the 
request. This is a result of the system generating the request not being listed m 
the appropriate configuration file on the receiving system. 
Insufficient Free System Resources 
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There are not enough free system resources on the system receiving the request 
for that system to assist with the distributed process. In some cases, a system 
may be to busy to even return this status value. 
Request Superceded 

5 This indicates that the system had enough free processor time, but chose to 

assist a different system in preference to the one sending the request. The 
reason that Request Superceded is a separate status code from Access Denied is 
that "Access Denied" may generate an error if encountered by a program 
searching for systems to assist it (to notify the user of a possible 
10 mis-configuration) while Request Superceded would simply indicate that the 

system is not available to assist with the task at that given time, and would 
therefore not generate an error. 
Task-Specific Error 

This is resumed by the code module that would handle the task. The 
15 MCMP^Status packet will contain an additional task-specific error code 

indicating the specific error which occurred. Task specific errors might include 
an error indicating that the system is not capable of assisting with the task due 
to a hardware limitation. 

20 The packet body of the assistance request packet consists of a 32-byte header, followed 

by a task-specific data area, which contains any infommation that the code module referenced 
in the Resource ID requires to assist in the processing of the task. This could, for example, 
include an image (if an image must be processed) or a description of a 3D environment to be 
rendered. 
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The task-specific data area also contains information indicating which ponion of the 
task the system is to work on (for example, starting and ending lines in the image) as well as 
the frequency with which the assisting system is to update the initiating system with processed 
data. 

The MCMP Header of the assistance request packet is: 
PacketType: DPP_AssistReq (hO002) 

PacketSize: 32 + Size of task-specific data 

ResourcelD's: One (The ID of the code module to handle the 

distributed process) 
Shuntable: No 



15 



ResourceReq; No 
The DPP_ AssistReq Header is; 
DPP_AssistReq Hdr,32 

ProcessID,2 SS Process Identifier 

30 S$ Reser\-ed 

The elements of the DPP_AssistReq Header are described in detail below. 
Process-ID: This is a 2-bvie integer value that identifies the process. It is assigned by 
the system initiating the process, and is a unique identifier when combined with that system's IP 
address. 

20 DPP.AssistResp: This packet is sent in response to a DPP_AssistReq to acknowledge 

that the system has begun assisting with the task. Because this is simply an acknowledgement 
message, there are no Resource ID's and there is no packet body. The MCMP Header is: 
PacketType: DPP_AssistResp (h0003) 

PacketSize: 0 
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ResourcelD's: None 
Shuntable: No 
ResourceReq: No 
DPP_EndTaskReq: This packet is sent to ah assisting system to instruct that system to 
5 cease assisting with a task prematurely (before the task is complete). This would be used, for 
example, if the user on the initiating system were to click a "cancel" button and abon the task. 
The MCMP Header is: 

PacketType: DPP_EndTaskReq (h0004) 

PacketSize: 16 
1 0 ResourcelD's: One (The ID of the code module to handle the 

distributed process) 
Shuntable: No 
ResourceReq: No 
The Packet Body of the end task request header is: 
15 DPP_EndTaskReq,16 

ProcessID,2 $$ ID of process to terminate 
,14 S$ Reserved 

DPP_EndTaskNotify: This packet is sent by an assisting system to notify the initiating 
system that it will no longer be assisting with a task. This is used both by itself, and as an 
20 acknowledgement to a DPP^EndTaskReq packet. This would be sent if, for example, the 
assisting system was to become too busy to continue to assist with the task, or if the assisting 
system was to be instructed by the initiating system to abort the task. This packet can also be 
used to notify an initiating system of a completed task. The MCMP Header is: 
PacketType: DPP_EndTaskNotif\* (hO005) 
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PacketSize: 
ResourcelD's: 



16 



Shuntable: 
ResourceReq: 



10 



One (The ID of the code module to handle the 
distributed process) 
No 
No 

The Packet Bodyof the end task notification packet is: 
DPP_EndTaskResp,16 
ProcessID.2 $S ID of process to terminate 
Tstatus, 1 $$ Task status; 1 -Complete, 0=lncompIete (Aborted) 
J 3 SS Reserved 

DPP.UpDateReq: This packet is sent by the initiating system to instruct the assisting 
system to transmit processed data (a DDP„UpdateResp packet). For example, if an image was 
being processed, this would cause the assisting system to respond with the data making up the 
portion of the image that it has processed so far. The use of this packet type depends on the 
1 5 task. Some tasks will not use this packet at all and will instead automatically generate 

DPP_UpdateResp packets at various intervals, and when the task is complete. The MCMP 
Header is: 

DPP_UpdateReq (h0006) 
6 

One (The ID of the code module to handle the 
distributed process) 
No 
No 



20 



PacketType: 
PacketSize: 1 
ResourcelD's: 



Shuntable: 
ResourceReq: 



The Packet Body of the update request packet is: 
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ProcessID,2 S$ ID of process for which to return processed data 

,14 $$ Reserved 

DPP_UpDateResp; This packet is sent from an assisting system to an initiating system. 
5 It contains the data that has been processed so far as part of the task in question. For example, 
if an image is being processed, this packet would contain the portion of the image that had 
already been processed. Note that the data sent in these packets in not cumulative. That is, if 
two packets are sent in succession, the second contains only data not included in the f rst. 
These packets are often sent in response to DPP_^UpdateReq packets, although they 
10 can also be sent automatically by the program handling the task assistance, both during the task 
and upon task completion. 

The packet body consists of a header, followed by task-specific data. All data not pan 
of the header is assumed to be task-specific data. 

The MCMP Header of the update response packet is: 

PacketType: DPP_UpdateResp (h0007) 

PacketSize: 1 6 + Size of task-specific data 

ResourcelD's: One (The ID of the code module to handle the 

distributed process) 
Shuntable: No 
ResourceReq: No 
DPP_UpdateResp Header is: 
DPP_UpdateResp,16 

HeaderSize,2 $$ Size, in b>ies, of DPP_UpdateResp header 

ProcessID,2 SS ID of process for which to return processed 
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data 

,12 $$ Reserved 

The term "code module" is used herein to denote a self-standing portion of an 
applications program dedicated to the performance of a specific operation of the applications 
5 program. For example, in a painting program, one code module may control the drawing of a 
line, while another code module implements the application of color and yet another code 
module is used for generating a geometrical figure such as a circle. These code modules are 
independent in that at least some of them are not required for executing any particular 
operation. Sometimes two or more modules are required to produce a particular result. 
1 0 However, in no case are all modules required. 

The term "machine-executable * as used herein refers to code modules which are 
proeram modules, capable of controlling computer operations and changing the state of the 
arithmetic logic circuits of a general purpose digital computer, thereby changing the 
functionality of the general purpose digital computer. Thus, "machine-executable code 
1 5 modules" do not include data files and other passive electronically encoded information. 

The term "applications program" as used herein refers to any executable collection of 
computer code other than operating systems and other underiying programming for controlling 
basic machine functions. Thus, the Modularized Code Master Protocol, including its 
subprotocols, is an applications program which is itself modularized and transmittable in code 
20 modules over a network. For example, at least some subprotocols will not exist on some 

secondar\' servers. Should such a subprotocol be required for a secondary' server to compete a 
task or process a user's request, then that required subprotocol may be transmitted over the 
network from the primary' ser\'er to the secondarv' server. 

Subprotocols are handled by including a subprotocol identifier in the MCMP Header 
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attached to each MCMP packet. On an MCMP server, the circuits for handling the 
subprotocols may be plug-in modules which are handled in real-time by the CMXP protocol. 
W^en an incoming packet is received, the appropriate subprotocol handler is called. The 
subprotocol handler can then process the packet in whatever way is required. A protocol 

5 handler becomes involved in the load distribution process because the MCMP server has no 
way of knowing what format the resources are in, how to transfer them between servers, or 
what the caching rules are. The subprotocol handler must deal with accessing, transfer, and 
caching of the protocol-specific resources. The subprotocol handlers are called periodically 
during the MCMP server's main processing loop, allowing ii to perform various maintenance 

10 tasks. Alternatively, the subprotocol handler could be called from a loop running in a separate 
thread. 

The handler for a specific subprotocol may request that the MCMP server flag a socket 
as being in a Proprietar>' Dialog Mode (PDM) On a PDM socket, all incoming data is passed 
directly to the subprotocol handler without being processed by the MCMP server. When a 

1 5 socket is retunred to normal operation from the PDM operation, the subprotocol handler must 
pass any "extra" unprocessed data to the MCNtP ser\'er, since it may have read a portion of 
one or more MCMP packets. 

The term "primary server'* or "source server" is used herein to denote the authoritative 
source for the resources relating to a particular application. For example, the primary server 

20 for the TenCORE Net Demo would be the server where the latest version of the demo was 
always posted. 

The term ''secondary server" as used herein denotes a server that receives 
service-handoffs from a primar>' server. A secondar\' server usually mirrors the content of the 
primary' sen/er for which it is secondary'. For example, a secondar\' server for the TenCORE 
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Net Demo would be a server that could take over servicing clients if the primary server became 
too busy. A secondary server does not necessarily contain mirrors of the resources for which it 
is secondary server, inasmuch as the secondary server can request these resources from the 
primary server as needed. 
5 A single machine is can be both a primary server and a secondary server. For example, 

a machine could be primary server for the TenCORE Net Demo, and secondary server for the 
Country Closet Clothing Catalog. 

A single machine can function as primary server for multiple applications, and can 
function as secondary' server for multiple applications. 
1 0 The word "resource'^ is used herein to denote any block of data that can be used by a 

server or client. A resource can be a file, a code module, a portion of a file, a code module, a 
portion of a code module, a file directory, a code module directory, or any related piece of 
information, including the CMXP Prohibited List. The term "resource" is also used to refer to 
hardware and system resources, such as processor time and memory. 
1 5 The term "tree-file" refers to a Catharon Tree-Structure Nameset File. A tree-file 

contains a series of named sets of records, which are grouped and nested imo a tree-like 
structure (similar to an operating system's file system). In tree files, names beginning with a 
percent sign are reserved for internal use. Any other names may be used by whatever 
application is maintaining the tree-file. Currently, only one percem-sign name has been 
20 assigned. It is "\%System" and it contains general information about the file, including 
(optionally) the name of the application that created the file, the user under who's network 
account the file was last edited, the date and time the file was last edited, the location of 
various resources in the file, the location of the default folder (if none specified), and the file's 
associated information. 
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As related hereinabove, TenCORE is an interpreted language which utilizes 
pseudocode. Interpreter programs suitable for use with the TenCORE programming language 
as modified in accordance with the above descriptions are in common use today. 

A description of the TenCORE programming language is set forth below. The basic 
5 characteristics of the language are discussed first, then the treatment of variables. Finally, an 
exposition is made of all the imponant commands used in the language. From this information, 
as well as the foregoing description, one of ordinary skill in the art can generate a modular 
programming language suitable for use in the invention. 
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TenCORE Language Basics ^ 

The TenCORE Language Authoring System is a complete programming environment 
specially enhanced for implementing computer-based training. Its editors aid in the creation of 
source code, images, fonts, screen displays and data manipulation. The language has complete 
5 facilities for display creation, response input and analysis, and data manipulation within a 
structured programming environment. 
Command Syntax 

The primar>- building block of the language is the command. TenCORE contains about 
1 75 commands mnemonically named for the functions they perform. Most commands are 
10 followed by a tag often with keywords that furher define the specific function desired. A 

command and tag taken together is called a statement. As in any language, there are rules that 
determine the syntax of a tag and how a sequence of statements interact to perform a specific 
task. 

The TenCORE language is a fixed field language. In the simplest form, the syntax has the 

1 5 form: 

command tag 

The command field contains the name of a command of up to 8 characters long. The fag 
field begins at character position 9 (there is a tab stop here in the source editor) and can be up to 
1 1 9 characters in length on the remainder of the line. For many commands, the tag can be 
20 continued for several lines by tabbing over (leaving blank) the command field on the following 
lines. Some typical lines of code look like this: 

at 5:10 
color yellow 

write Welcome to Basic Sign Language 
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Today's lesson consists of.,. ^ 

Each statement begins with a command and is followed by a tag. In the first line, the at 
command causes the cursor to be positioned on the fifth line and temh character position of the 
display. The second color command selects yellow to be used for following graphics and text. 
5 The last write command puts text on the display at the position and color previously specified. 
The write statemem's tag continues over several lines by tabbing over succeeding command 
fields. 

Selective Form 

Many commands have a selective form' 
10 command SELECTOR. negTAG. zeroTAG. oneT.A.G.. , .nTAG 

The SELECTOR is an expression consisting of variables, constants or calculations that is 
evaluated and used to select a specific lag from the list. The tags are usually separated by 
semicolons although other separators are available The iiTAG case is selected when SELECTOR 
evaluates to n or greater A blank entry in the list ( .. ) can be used to skjp execution of the 
1 5 command tor a specific case. If day is defined as an integer variable programmed to hold a 

panicular day of the week, then the following statements would display that day on the screen 

at 5:10 

write Today is 

writec day;;; Monday; Tuesday; Wednesday; Thursday; 

20 Friday; Saturday; Sunday 

Since TenCORE defines logical inie to be the value -1 (or any negative value) and false 
to be 0 (or any positive value), any two tag selective acts as a true or false decision: 
command SELE,CTOR; trueTAG; falseTAG 
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Conditional Form ^ 

Some commands (especially the judging commands) have only a CONDITION as the lag 
that is used to determine if the command executes or not. The condition is any expression that 
logically evaluates to true (-1) or false (0). 
5 command CONDITION 

For example, if you wanted to accept misspellings after a student's third attempt at 
matching a response, you could use a conditional expression based on the system variable ztnes 
v^'hich holds the number of previous judging attempts. 

okspeil ztnes > 3 
10 answer Mississippi 
Embedding 

Many text handling commands allow the embedding of further commands m the body of 

the text 

command TEXT «command,tag» TEXT 
15 The symbols « and » are the embedding symbols accessed by the [.\LT][.] and [.*^LT][ ] 

kevs Frequently, the embedded command name can be abbreviated to the first letter or two to 
save space: e g.. the abbreviated form of the embedded show command is simply s. Embedding is 
frequently used for display of variables and the control of plotting attributes within texi 
statements thereby effeciently coding for an entire display: 

20 write «color , red»Your score «coior , white» is «show , score»% . 

The «c ,green» class average «c,white» is c<s , average»% . 

Comments. Spacing and Continued Commands 

An asterisk (*) at the beginning of a line marks the entire hne as a comment that is 
removed by the compiler and has no effect on execution. A comment can be placed on any line of 
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code by placing it after double dollar signs SS: the compiler removes the comment and it does not 
affect the execution of the code: 

calc te«p c= teinp»9/5 + 32 $$ convert centigrade to Fahrenheit 

Normally, trailing spaces on a tag are removed by the compiler and do not affect 
5 execution. This is also tme when double dollar SS comment signs are used: the compiler removes 
the comment and any spaces back to the real tag. For some text commands, you may actually 
warn the trailing spaces and can direct the compiler to maintain them by using an on-line 
comment with triple dollar signs SSS. The following example would display something like 
Welcome Bob: 

10 write Welcome $S$ maintain single trailing space 
showa name 

Most commands with non-selective tags can be repeated agam without the need for 
typing in the command field again. "Space" can also be added between most Imes of code to 
make the coding read well: 

* ^^^^ section of code initializes paraxneiiers . 

calc fraine c= 2045 $S starting fraine number 

file <= -bangs' $$ use the explosion library 

block cr 'mega* $$ use the big explosion 

type c= •namesef $$ these are nameset files 

20 attach file; type $$ attach the file 

Units 

A sequence of TenCORE statements makes up a functional emity called a ;/;;// analogous 
to a procedure or subroutine in other lanauaees. 

Commands can be grouped into units in any way that makes sense. Simple "page turning" 
25 lessons consist of multiple frames of material: each could be a unit. A complex graphic that is 
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used several places in a lesson can be put once into a single unit which is then referenced at each 
point it is needed. A simulation can have each functional pan in its own unit. 

Each unit must have a unique name of up to 8 characters in length staning with a letter. 
Punctuation, special symbols and the two system reserved names x and q are not allowed. 
5 Referencing Units 

If you want to reference a unit in the same lesson, you simply state the unit's name: 

do clock $$ call unit clock to start timing going 

If you want to access a unit in a lesson different from the one currently executing, then 
you must give both the lesson and unit names. 

10 do maps ,illinois $$ show the map of Illinois 

Finally, you may not want to explicitly state the unit or lesson names but rather refer to 
names that have been calculated into variables This is done by embedding the variables where the 
explicit names would normally appear. Embedding consists of surrounding the variables with the 
« and » symbols. For example, say that all the lesson and unit names in a project have been put 
1 5 into the 8-bue arrays lessons and uniis. then any unit can be accessed by setting the indices to 
point to the desired unit: 

do «lessons (i) » , «units ( j ) » 

Generic Unit Names 

System keyword names exist to provide generic branch destinations to main units in the 
20 current lesson or back to the system. For example,=next and =back can be used for the unit 

name when jumping to the next or previous main unit in the current lesson; =exit can be used to 
exit the current lesson back to DOS. the editor or the system Activity Manager. A descriptive list 
of the nine generic unit names along with examples of their use is found with the jump write-up. 
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Unit Terminologj* ^ 

Units can play a number of different roles during execution depending on how they are 
used. Units may correspond to major displays and imeracuons that a user experiences: the 
. "pages" of the lesson. On the other hand, a unit may simply be a subroutine called by one of these 
5 major units to perform a sub-task. The following terms are used to describe various functional 
units. 

main unit 

A main unit is the first unit executed in a lesson and any other unit reached by a jump 
type branch. It normally corresponds to one "page" or user situation m the lesson, h is the 
10 staning point for all user interaction. When the end of the main unit is reached in execution, the 
system waits for a key press or other interaction to occur to branch the user to another main unit 
Branching to a new main unit normally, 
erases the screen 

re-initializes all plotting parameters 
1 5 • resets branches to their lesson defaults 

clears all pointer areas 

establishes a new main reference point in the lesson 
current unit 

The current unit is the unit currently executing, h may be the main unit or a subroutine 
20 unit called from the main unit by a do or flow command, 
done unit 

A done or called unit is used to describe a unit executed as a subroutine. When the end of 
a done unit is reached, control returns to the command following the calling command in the 
invoking unit or to the waiting state from where a now branch was triggered. 
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base unit 

The base unit is the main unit at the time a branch occurred that was modified with the 
base keyword. It can be used to set up a common help sequence that can automatically return to 
whatever main unit called it. Return to the base unit occurs through a branch using the =base 
5 generic name. 

startup unit 

The startup unit is the first unit executed in your lesson either from DOS or a router such 
as the system Activity Manager. Ii is usually the first physical unit in the lesson file and should 
contain a startup command if the unit is to be directly entered from DOS. 

10 restart unit 

A restart unit is placed in the lesson flow where return from an interruption in the 
learning session can occur. It would generally have a restart command in it and should have a 
display that can re-orient the student after the interruption. The system Activity Manager would 
branch a user to one of these units if the "continue last lesson" option is chosen upon student 

15 signon. 

Control Blocks 

Control blocks offer a means to expand control of major events such as staning or 
quitting a lesson or in going from one main unit to another. Coding in a lesson's control blocks is 
automatically executed at these major events regardless of the specific starting, ending or main 
20 unit involved. This is a convenient way to ensure that necessan.- inuializations or cleanups are 

done. Control blocks are created in the editor on the block directory* page. Besides the following, 
sjome additional control blocks are discussed in the Updates chapter. 
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-(-initial " 
The code in a ■^initiaI control block is executed each time an outside jump type branch is 
made to the lesson: e.g., staning the lesson from DOS, executing the lesson from the editor, 
jumping to the lesson from another lesson or from the Activity Manager. It can be used to load 
5 fonts, set plotting conditions, initialize data keeping, etc. regardless of where entry to a lesson 
occurs, 
■i-main 

A -t-main control block is executed each time a new main unit is entered: it is used to 
perform operations common to the beginning of all the main units in a lesson. For example, it can 
1 0 be used for: displaying a lesson-wide background image and flow bar, saving restan information, 
or displaying debugging information during lesson editing such as the current main unit name, 
-t-exit 

A -i-exit control block is executed whenever control leaves the current lesson as during a 
jump to a different lesson or when quitting to DOS or to the calling program that staned the 
1 5 current lesson running. It can be used, for example, lo collect end-of-lesson summan.- information 
or to turn off any devices that were turned on for the lesson, 
•♦■editor 

A -i-editor control block is executed each time you go to edit the file. It can be used, for 
example, to load fonts for text editing. 
20 Screen Resolution 

A wide range of PC display hardware is supponed from the original CGA and EGA 
adapters to MCGA, VGA and Enhanced \'GA adapters.- Each of these includes an increasing 
collection of graphic and text screen resolutions and color capabilities. TenCORE courseware is 
typically created using a specific screen resolution and color range that is supponed on the target 
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population of run-time machines for your courseware: often the lowest common denominator is 
used. The screen command selects these parameters and is usually placed in the +initial control 
block of a lesson. 

Graphic Coordinates 

5 A panicular screen pixel is addressed by x and y graphic coordinates with 0,0 specifying 

the lower left comer of the screen; 

dot 100, 200 $$ write the pixel at x=100, y=200 

at 320, 240 $$ at the center of the vga screen 

circle, 75, fill %% draw a filled circle of radius 7 5 

10 Most display commands update the system variables zx and zy as part of their operation 

and thereby define the current screen location. 
Character Coordinates 

Text can be more conveniently addressed by character coordinates that specify a line 
number and character position that are separated by a colon to distinguish them from graphic 
15 coordinates: 

at 5:15 %% line 5 character 15 

write Text on line 5.... 

Defaults 

Graphics and text commands display using the current settings for numerous attributes 
20 such as; the foreground and background colors, the plotting mode, text size and drop shadowing, 
etc. These attributes can be set just prior to using them: 



polor yellow $$ the following in yellow 

mode write %% overs trike plotting mode 

25 text shadow; on SS drop shadowing on text 
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text size; 2 $$ size two fonts ^ 

5:10 $$ at line 5, character 1 

write A cross section of the sun. . . 

Attributes have initial default values that are set by the system when executing an initial 
5 or screen command as at the stan of a lesson: e.g., the system default foreground color is white 
and the text size is 1. Attributes are automatically returned to their default values at the stan of 
each main unit or they can be forced as a group to their default values at any time by use of the' 
statement status restore: default. Upon jumping to a new main unit after executing the above 
example code, size 1 text and color white would be put back in operation. See the initial 
1 0 command for a list of the display attributes and their standard default values. 

To give a common "feel" to a lesson, it is conveniem to set the attribute values to your 
default values at the stan of all units in the lesson. That way. if you later change your mind about 
using. sa>-. the gothic font throughout a lesson, you can merely change the font default value to 
something else and have it apply to the emire lesson The status save: default statemem is used 
1 5 to reset the attribute defaults to their current values: 

color yellow 

text spacing; variable 

text shadow , on 

text nvargin; wordwrap 

20 status save; default $S the above are now lesson defaults 

Lesson defaults are usually set in the +initial control block of a lesson. 
Variables 
Author-Defined Variables 

TenCORE suppons both local and global variables. 
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Local variables are defined in a specific unit and are available only to that unit. When a ^ 
unit is exited, either by reaching the end of the unit or by branching to a new main unit, the values 
of its local variables are lost. 

Global variables are available throughout the lesson in which they are defined and retain 
5 their values for the entire program. With the help of the TenCORE Activity Manager or a similar 
program, global variables can even be made to retain their values across TenCORE sessions. 
Local Variables 

Local variables are created by defining ihem within a source unit, between a define local 
and a define end statement. 

10 de£lne local 

height, 2 $$ defines the 2-byte integer variable height 
length, 4, r S$ defines the 4-byte real variable length 
define end 

Variables defined in this way are known only to the unit in which the definition occurs, 
15 and the values assigned to these variables are lost when the unit is exited via any command which 
goes to a new main unit- 
Local variables are usually used for temporars' information which is not needed outside 
the current unit, such as loop indexes. 
Global Variables 

20 A special block, called the defines block, is normally used to hold global variable 

definitions. Within the defines block, variables are defined by insening lines of this form: 
name,si2e[,type] 
as in: 
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defines 

height, 2 $$ defines the 2 -byte integer variable height 
length, 4, r $$ defines the 4 -byte real variable length 

Variables defined within a defines block are global variables. They are available in ever^' 
5 unit within the file, and are normally used to store informafion which is needed in several places, 
such as the user's name or status within the proeram. 

Global variables for every lesson are stored from the beginning of a single memory area 
reser%-ed for global variable storage. This means that if a program extends over two or more 
source files, u is important that all source files use the same defines and/or coordinate their shared 
10 use of this area. This subject is treated in more depth in the Physical Allocation of Variables 
chapter 

Local Definition of Global \'ariables 

Similar to local variables, global variables can be defined between a define global and a 
define end statement. 

1 5 def i ne global 
height , 2 
length , 4 , r 
define end 

\-ariables defined between define global and define end use the global variable storage 
20 area, but are known only within the unit in which the definifion occurs. 

The define global command should be used only for isolated test units and a few special 
purpose utilities. Used without an understanding of how space for global variables is allocated, 
-the define global command can lead to conflicting definitions of variables and unpredictable 
program behavior. For more information, see the Physical Allocation of Variables chapter. 
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Precedence of Variable Names 

A local variable can be given the same name as an existing global variable 
local variable supercedes the global variable, 
globals (defines block) 

5 user, 20 
screen, 5 

define local 
user , 4 , r 
10 define end 

Here "user" has been defined as both a global and a local variable. Within unit screenS, 
the elobal variable "user" cannot be accessed Any time that "user"' appears m unit screenS. it 
refers to the local variable 
\'ariable Names 

15 \'ariable names can be one to eight characters long. .Any of the following may be used in 

variable names: 

• letters (including those in the extended character set. such as A and o) 

• numerals 

• period (.). undedine M. caret( ") and tilde (^) 
20 • extended ASCII characters 

The first character of a variable name may not be a numeral or a period. Some samples of 

valid variables names are: 
username 
Lesson 
25 xLOCAT 
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X. loc 



last X 



■ list 



root 



5 



Invalid variable names include; 



2student 



may not start with a numeral 



useraddress 



name longer than 6 characters 



uni t * n 



punctuation not allowed 



Case is significant- the variable "a" is different from the vanable "A" and the variable 



10 "alpha" is different from the variables "Alpha" and ".ALPRA". 

Spacing around the elements of a variable defmition is not sigmficant. Most authors apply 
one of two different styles in defining variables 

define local 
width , 2 
15 height, 2 
area , 2 
length , 2 
mas s , 4 , r 
define end 

-° 1" Style above, the length and type of each variable are written immediately after the 

vanable name. Another common style is the followinc; 

define local 

width , 2 

height ,2 

25 area ,2 

length ,2 

mass ,4,r 
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#«• 

define end 

In this style, the lengths of all the definitions are aligned in a tabular format 
These styles are fijnctionally equivalent. 
Variable Types 

i Any of the three types can be defined globally or locally. Variables in TenCORE are not 

"strongly typed", i.e. a variable defined as one type can often be used in operations primarily 
intended for another type of variable. 
Integer \'ariables 

Integer variables store posiiive and negative whole numbers. Integer variables are defined 
3 as follows: 

x,2 

line , 3 
teir^ , 4 
5 total, B 

Where the normal form is name, size. The size of an integer variable can be 1. Z, 3, 4. or S 
b\tes. The size determines the ranee of values that the variable can store. 



size 


i Range 


1 I -12810 12* 


-I 


1 -32"6ii 10 3276: 




1 -8.38S.60STO S.53S.60" 


4 


1 -2.147.455.648 lo 2.147.483.647 


8 


1 -9*10'^o-9M0" 



Integer variables are signiilcam for all values within their range: no roundina errors occur 
from addition, subtraction, or integer multiplication of integer values. However, roundine is 
20 performed when real values are assigned to integer variables and when integer division is 
performed. 
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IntegeMype variables optionally take the type modifier integer, which can be abbreviated 



as i: 

line , 3 , integer 



TenCORE stores integer values in natural (high-b\ie to low-byte) order. (Many MS-DOS 
programs store integer values in low-b>te to high-byte order.) 
Real Variables 

For storing non-integer numeric values. TenCORE provides real variables, which are 
10 defined as follows 

force, 8 , real 
area , 4 , r 

Where the normal form is namL'.size.rtal Real \ ariabies can be either 4 or 8 hues long, 
and the tag real or its abbreviation r must follow the size specillcation when the \ ariable is 
15 defined 

The size of a real variable determines the range of values that the variable can store and 
precision, measured in sigiujicani digiis. with which the variable can store the value. 



Size i 


Range 1 


Significant Digits 


' i 




6 


S 1 


10^- i 


15 



Eight -b>ne real variables should be used whenever storage space is not at a premium. If 4- 
byie real variables must be used, they should be compared only to other 4-b>ie real variables. 
20 Comparisons of the form iflength = 1 .1 can give unexpected results due to the limited precision 
of 4-b\te real variables. 

Real variables are stored in IEEE format. As in the case of integer variables, the bynes are 
stored in natural (high-to-low) order rather than the reverse order used b>- some programs. 
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A variable declared with no size and no type is created as a 4-b\ie real variable. 
Non-Numeric Buffer Variables 

For holding text or other information, non-numeric variables can be defined with any size 
from 1 b\ie to 32767 bytes (provided that enough variable space is available), as in: 

5 username,20 
unitnautve ,6 
italics, 2052 

The general format is name, size. Non-numeric variables are most often used to store text, 
but they can also be used to store any other information requiring a buffer. 
10 There is no difference between the definifion of a non-numeric variable with a length of 1, 

2, 3, 4 or 8 b>ies and the definition of an integer variable of the same size. Only the context in 
which the variable is used indicates whether the variable holds integer or non-numeric data. 
In TenCORE command syntax, non-numeric variables are referred to as "buffers". 
Arrays 

1 5 The variable types described so far are all scalar, meaning thai each variable holds only 

one value. TenCORE also suppons array variables An array is a series of variables of the same 
size and type, all referred to by the same name, using an Duiex to specify- individual elements of 
the array. An array index is simply a number in parentheses which appears immediately after the 
name of the array. 

20 average (100) , 4 , real $$ array of one-hundred 4-byte reals 

count (5) ,2,i SS array of five 2-byte integers 

bignaim(20) ,8 $$ array of twenty 8-byte integers 

stable (10) , 256 $$ array of ten 256-byte non-numeric variables 
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The definifion of an array variable looks like the definiiion of a scalar variable, except that 
the vanable name is followed by a number in parentheses which specifies the number of elements 
(values) the array should hold. The general form for defming an array is: 
naniefelementsjjize. type 
5 Arrays can then be referenced in TenCORE code as in: 

calc count (3) c= 10 

datain 1 , table (index) , 1 

Brackets are synonymous wuh paremheses. permitting the following alternative notation. 

caic count[3] c: 10 

0 dataxn 1 , table { index ], 1 

TenCORE suppons only one-dimensional arrays, arrays of two or more dimensions can 
be simulated using functions 

System-Defined Variables 

TenCORE provides a number of svstem-defined variables which store information about 
5 the currem state of the proizram These system-defined variables lusually shonened to system 
variables) are simply names which TenCORE recognizes as represemmg numbers or other 
variable information. 

System variables provide information which is frequently needed or which might be 
tedious or impossible for the author to maintain in author-defmed variables 
:0 For instance, the system variable ztries can be used to refer to the number of times the 

user has entered a response to the currently active arrow structure: 
if xtries > 3 

write The correct answer is: green 

endif 
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This example displays the correct response to a question if the user has already tried to 
answer more than three times. 

System variables all begin with the letter "z'\ This makes them easier to recognize. As a 
matter of good programming style, auihor-defmed variables should therefore avoid names which 
5 begin with "z". It is possible to create an author-defmed variable with the same name as a system 
variable. In this case, the author-defmed variable has precedence and the value of the system- 
defmed variable becomes unavailable 

The following are examples of some other system variables 

• zreturn is set by many commands to indicate the success or failure of the command. A 
10 neeative value of zreturn indicates success, while various non-negative values indicate 

different reasons for failure of the command zreturn is a one-bue mteger reilecting 
command siafus. 

• zcolor is set to the value of the current toreground plotting color. It is a iwo-bvie integer 
relating to display coiurol 

15 • zmainu contains the name of the current mam unit It is an eieht-b\ie variable relating to 

branching 

Values cannot be directly assigned to system variables. However, some system variables 
are affected by an associated conamand: for instance, zcolor indicates the currently selected 
foresround color and is therefore affected by the color command. Executing color white+ sets 
20 zcolor to 15, the value corresponding to bright white. 

A comprehensive list of system variables organized according to categor^• follows. In 
addition, many command descriptions refer the reader to system variables affected by the 
command. 
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System Variables ^ 
zareacnt 2(inl) Number of areas currently defined 

zareahl 2(int) Area ED of currently highlighted area (0 if no area highlighted) 
zargs 1 (int) Number of non-null arguments actually received by either a -receive-or by 

5 the return argument list of a -do 



zargsin 


- r(int) 


Number of arguments sent by -do-, jump-, or -jumpop 


zargsout 


l(int) 


Number of arguments the invoking unit expects returned 


zaspectx 


2(ini) 


x-aspeci ratio correction factor 


zaspect}- 


2(im) 


y-aspect ratio correction factor 


zauthsys 


l(int) 


Indicates the TenCORE executor type: 



-1 = LAS author executor (TCALTHOR EXE) 

0 = student executor (TCRL^'.EXE) 

1 = Producer executor (TPR.EXE) 



zbinan- 1 (im)Type of file from which "zlesson" was loaded" 

-1 = binar)', 0 = LAS source, 1 - Producer source 
zcharb 2(int) Offset of standard size 1 font baseline 

zcharh 2(int) Height in dots of standard font or charset 

zchanv 2(int)Width in dots of standard font or charset Note, all text positioning is 

based on the standard font (zcharw, zcharh, zcharb), not the current font. 



zclipxl 


2(int) 


X-coord of lower left corner of clipping area 


zclipx2 


2(int) 


X-coord of upper right corner of clipping area 


zcHpyl 


2(int) 


Y-coord of lower left corner of clipping area 


zclipyZ 


2(int) 


Y-coord of upper right corner of clipping area 


zclock 


4(int) 


Value of the system clock, accurate to ^55ms 
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zcolor 2(int) Foreground color set with -color 

zcolore 2(int) Erasure color set with -colore 

zcolorg 2(mt) Background color set with -colorg 
zddisk l(mt) DOS default drive: 1=A:, 2=B:, 3=C: 

5 zdisk l(int) Method of searching for data files: Values same as "zedisk" 

zdisks 4(bits)Bitmap of drives TenCORE can access, set in DOS by SET CDISKS= 

zdispiay l(int) Current active display number (dual screen driver only) 
zdispx 2(int)X-size of current window 

zdispy 2(int)Y-si2e of current window 

10 zdolevel 2(int) Current level of do type command stack 
(do, libran-, flow do. flow libran-) 
zdomcnt 2(int) Number of existing domains 
zdomname S(alpha)Name of current domain 
zdompar 8(alpha'»Name of parent domain 
15 zdoserr l(int) DOS disk error code Set only when "zreturn" = 0, indicating a disk error' 

0 disk is wriie-protected 
2 rive not ready (door open or bad drive) 
4 CRC error (error detected in data) 
6 seek error (bad drive or diskette) 
20 7 unknown media type (unrecognized diskette) 

8 sector not found (bad drive or diskette) 
12 general failure (bad drive or diskette) 
zdosver 4(alpha) DOS version number in the format "X.XX" 
zedisk l(int) Method of searching for source/binar\^ files: 
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-1 = search all drives; 0 = search only "zddisk" 
-2 = search only system pseudo-drive 
1, 2, 3,... = search only drive A., B:, C. 
zedoserr 8(ini) DOS extended error code, sei when "zreturn" = 0. \ alid only when 
5 running under DOS 3.0 or higher. The format is: 

2 bytes error code 
1 b\ie error class 
1 h\ie actions 
1 b\ie locus 

10 The remaining three b>ies are reserved, 

zenable 4(bits) -enable- flags 

This variable is a set of bus numbered 1 to 32. Cenain its correspond to -enable- 
commands as follows 





1 


enable absolute 




(reser\'ed) 


15 




enable pomter 


10 


(reser\*ed) 




3 


enable mode 


n 


(reser\'ed) 




4 


enable cursor 


i: 


enable break 




5 


enable ptrup 


13 


enable arrow 




6 


enable font 


14 


(reser\'ed) 


20 


7 


enable area 


15 


enable fillbreak 




8 


(reserv'ed) 


(bus 14-32 reserved) 



Use the bit() function to test "zenable": For instance, bit(2enable.2) is -1 if 
the pointer is enabled and 0 if not 
renvlen 4(int) Length in b\nes of DOS environment buffer 
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zenvloc 4(ini) Absolute memory location of DOS environment buffer 
zerrcode 2(int) "error code" value from "zedoserr" 

zerrlevl 2(int) DOS variable "errorlevel" as return from last exec file.- command 
zerrorl 8(alpha)Lesson name of unit to execute if an execution error occurs, set by -error 

5 zerroru 8(alpha)Unit name of unit to execute on execution error 
zexitbin l(int) Type of file from which =exit branch will be loaded: 

-1 = binar\*; 0 = source; 1 = tpr 
zexitl Sfalpha) Lesson name to branch to on -jump =exit 

zexitu 8(alpha')Unit name to branch to on -jump =exit 

1 0 zfcrecs 4(int) Number of contiguous free records in the attached nameset type file 

zfdisk l(int) Disk on which the attached tile resides. 

1 = drive A., 2 = drive B:. etc 
-2 = system path 
zflowcnt 2(int) Number of tlow branches currently defined 
15 zfnanie S{alpha )Name of the attached file. G if none attached 

zfnames 2(int) Total number of names in the attached file: has no meaning for datasei files 
zfontb 2(int) Offset of current font baseline 

zfontf 4 (biis)For font groups, specifies which of the attributes were fit correctly and 

which were synthesized. Bits defined as follows; 
20 6 = Bold attribute matches request 

7 = Italic attribute matches request 

8 = Size attribute matches request 

16 = Narrow attribute matches request 
22 = Bold Synthesized 
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23 = Italic Synthesized 

24 = Size Synthesized 

For the bits above that are symhesizable, the attribute may not match the request 
but also may not be synthesized; for example, if the font group only has bolded 
5 items, and the current attributes specify non-bolded, then bits 6 and 22 will both 

be off 

zfonth 2 (int)Height in dots of currently active font 

zfontret 1 (int)Information on how closely the selected font fits the requested 

parameters. .^1 values available for font groups, For fonts, values -1, 2 and 3 are 
10 possible. Set by -font-, -text-,status restore-. 

-2 = panial match, some synthesis required 
- 1 = exact match 

= panial match, some non-synthesizable attributes could not be matched 
1 = no suitable match found; base font is in effect 
15 2 = base font not available: standard font is in effect 

3 = standard font not available; charsets are in effect 
^font^v 2(int) Width in dots of currently active font 

zforce 2(bits)force- flags 

This variable is a set of bits numbered 1 to 16. Certain bits correspond to -force- 
20 commands as follows: 

1 force cursor lock-zinfo 8(int) Associated information b\tes for the 
selected name in the attached file; has no -meaning for dataset files 

2 force number lock- 

3 force extended- 
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5 zfrecs 
zfrombin 

zfromd 
zfrom 



10 



zfromu 
zfrecs 
15 zfn-pe 

zfunames 
zfurecs 

20 zfver 
zhcolor 
zhcolore 
zhcolorg 
zhdispx 



4 force charset- 
(bits 5-16 unused) 

Use the bii() function to test "zforce". For instance, bit(zforce, 1) is -1 if -force 

cursor lock- is in effect and 0 if not 

4(int) Total number of data records in the attached file 

1 (int) Type of file from which "zfroml" was loaded: 

-1 = binar>'; 0 = source; 1 = tpr 

Uint) Drive from which "zfroml" was loaded. Same values as zldisk 
8(alpha)Lesson name of unit which invoked current unit via -do-, -libran -. or 
main-unit branch 



zfromlin 2(int) Line number of command in "zfromu" which which invoked the current 



umt 

8(alpha)Unii name of unit which invoked current unit 

4(int) Total number of data records in the attached file 

8(alpha)Type of the attached file. 0 if none attached: file types: source, tpr. 

dataset. nameset.binar>\ rosier, course, studata. and group 

2(int) Number of names used in the attached file 

4(int) Number of records used in the attached file; has no meaning for dataset 
files 

4(alpha)TenC0RJE version which created the attached namesei as "X.XX" 
2(int) Hardware color set set with -color 
2(int) Hardware erasure color set whh '-colore 
2(int) Hardware background color set with -colorg 
2(int) Physical x-size of current screen type 
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zinfo 8(int) Associated information b>aes for the selected name in the attached file; 

has no meaning for dataset files 
zinput 2(int) Keypress value of last key processed 

0 no input 

5 1- 255 standard or extended character 

> 255 non-character' keypress 

"zinput" contains 2-b\ie keypress values. To determine if "zinput" contains a 
particular value, one of the following forms is required: 
zinput=%"character" zinput=%alt"character" 
10 2input=%ctr'character" 2input=yoaltctr*character" 

2input=%keyname 

The %alt, %ciL and °/balictl modifiers operate on single standard ASCII characters 
(h20 - h7f). The % modifier operates on standard and extended characters (h20 - 
hOff) in double quotes and on named keys 
15 zinputa 2(int) .\rea ID of area causing the current zinpui value (0 if zinput was not 

generated by an area), set when zinput updated 
zinputainfo 8(int) Value of info tag for area that caused this branch 
zinputf 4(bits Keyboard and pointer status at last input 

This variable is a set of bits numbered 1-32. Certain bits correspond to keyboard 
20 and pointer status as follows: 

1 Insen turned on 

2 CapsLock turned on 

3 NumLock turned on 

4 ScrollLock turned on 
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5 


either Alt key down 




6 


either Ctrl key down 




7 


left Shift key down 




8 


right Shift down 


5 


9 


SysReq key down 




io 


CapsLock key down 




11 


NumLock key down 




12 


ScrollLock key down 




13 


right Ail key down 


10 


14 


right Ctrl key down 




15 


left -Mt key down 




16 


left Ctrl key down 




17 . 


enhanced keyboard "extra" key 




18 


key is from .AJt-numbers 


15 


19 


key is from pointer action 




20 


key is from "pointer up" action 




21 


key is from touch device 




(bits 


22-29 reserved) 




30 


middle mouse button pressed i 


20 


30 on a middle button press) 




31 


right mouse button pressed 




32 


left mouse button pressed 



Use the bitQ function to test "zinputf. For instance, bit(zinputf,2) is 1 if 
CapsLock was turned on during the input in "zinput", and 0 if not. 
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zinputx 
zinputj^ 
zintincr 
zintnum 
5 zkeyset 



10 



20 



zldisk 



zlength 
zlesson 
15 zlident 
zline 
ziinfo 



ziname 



zmainl 
zmainu 
c zmargin 
zmaxarea 



2(int) Graphics x location of pointer when *'zinput*' was last updated 

2(int) Graphics y location of pointer when "zinput" was last updated 

2(int) Minimum significant increment for I value in -palette 

1 (int) Interrupt number used by TenCORE device drivers 

2(int) shift flag byte and scan code of last key processed. 

high byte = shift flags 

low b\ie = scan code 

The high b>ie is a set of bits numbered 1-S. duplicating the first eight bits in 
"zinputf* 

The low b\te is a "scan code" identifying a physical key 

l(int) Drive from which the currently executing lesson was 

loaded. L2.j..=A:,B;,C:..., •2=sYSiem drive 

2(int ^ Length of judging buffer after -put 

8(alpha) File name of current unit 

8(alpha) Identification stored in current binary file 

2(int) Current character line 

2(int) Number of b\ies of associated information for the attached file; has no 
meaning for datasei files 

2(int) Maximum length of a name in characters for the attached file; has no 

meaning for dataset files 

8(alpha) File name of main unit 

8(alpha) Unit name of main unh 

2(int) x-coordinate of left text margin 

2(int) Maximum number of areas; default= 1 000 
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zmaxcol 
zmaxdom 
zmaxflow 
zmaxpage 



zmlength 



zmem 

zfmem 

zrmem 

zxmem 

zmode 



zmouse 
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2(inl) Maximum number of colors available on current display ^ 

2(int) Maximum number of domains allowed 

2(int) Ntaximum number of flow branches that can be defined 

2(int) Number of available hardware display pages 

4(int) Size, in bvtes, of the last-referenced memory block. 

Due to Windows memory management and disk swapfile, the effective memory 

pool size is generally more than large enough for most TenCORE needs on a 

typical Windows system. However, you should always check zreturn because it is 

possible for memorv-related commands to fail panicularly on Windows systems 

with low memon,'. For compatibility reasons, the system variables zmem, zrmem 

and zfmem never return a value greater than 512K (524,288). However, if enough 

memory is available, a memor\* block as large as 1,048,560 b\tes (hex FFFFO) can 

be created. .\lso for compatibility reasons, zxmem always returns a value of 0. 

4(int) Current size, in bvies, of memor>' pool 

4(int) Largest block that could be allocated in the memory pool 

4(int) Largest block that could be allocated in the memorv' pool 

4(int) Set to 0 

2(int) Current screen display mode 

0 = inverse 3 = write 6 = add 

1 = rewrite 4 = noplot 7 = sub 

2 = erase 5 = xor 
l(int)Indicates if the mouse device driver is loaded: 

-1 = mouse driver loaded; 
0 = not loaded 
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zmstart 



zmxnames 
5 zname 

zndisks 

znindex 
10 znumber 
zoriginx 
zoriginy 
zpaiincr 
zpcolo 

15 

zplotxh 
zplotxl 
zplotj'h 
zplotyl 
20 zrec 

zreturn 
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4(int) Absolute address of the last-referenced memory block. 

The top two hues are the segment and the bottom two bytes are zero to conform 

to a standard absloc address usable in memloc(a,zmstart) 

4(int) Maximum number of names permitted in the attached nameset type file 

8(alpha)First 8 characters of the selected name in the attached file; has no meaning 

for dataset files 



l(int) Number ofdrives defined within DOS as set by LASTDRIVE= 
CONFIG.SYS 



in 



2(int) Position of the selected name within the attached nameset type file 

2(int) Number of replacements made with -put 

2(int) Relative \-coord of origin as set with -oridn 

2(int) Relative y-coord of origin as set with -origin 

2(int) Minimum significant increment for R, G, and B values in -palette 

2(int) Color of dot of last pointer input location: in text mode.foreground color 

of character 

2(int) Upper x text extent (see text measure 
2(int) Lower x text extent (see text measure 
2(int) Upper y text extent (see text measure 
2(int) Lower y text extent (see text measure 

4(im) Number of records associated with the selected name in the attached file; 
for datasets equals "zfrecs" 

l(int) Indicates the success or failure of a command which sets this system 
variable, "zreturn" is generally set by commands which access disk or the 
TenCORE memory pool. Possible values for "zreturn" are: 
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15 



20 
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2 Redundant operation 

(no action taken) 

- 1 Operation successful 

0 Disk Error: see "zdoserr" 

1 No file attached 

2 Block out of range 

3 Memory or value out of range 

4 Does not exist 

5 Invalid device selected 

6 Duplicate name 

7 Directory full 

8 Insufficient disk records 

9 No name in effect 

1 0 Name or block not found 1 1 Invalid type 

1 2 Invalid name length 

1 3 Invalid information length 

14 Too many names/records in nameset 

15 Nameset directory corrupted 

16 Invalid name 

1 7 Invalid image or data 

1 8 Unable to fill memory pool requests 

19 Operation invalid in context 

20 datain- on locked data 

2 1 Conflict with another user's lock 
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zrmargm 
5 zrotate 
zrotatex 
zrotatey 
zrpage 
zrstarti 

10 zrstartu 
zscaleox 
zscaleoy 
zscalex 
zscaley 

15 zscreen 



20 
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22 Too many locks on one name 

23 Screen coordinate out of range 

24 Required name/record lock not found 
2(int) x-coordinate of right text margin 
2(int) Number of degrees of rotation 
2(int) x-coordinate of rotation origin 
2(int) y-coordinate of rotation origin 
I(int) Display read page set by -page 
8(alpha)Lesson name of restart unit, set by -restart 
8(alpha)Unit name of restart unit, set by -restart 
2(int) x-coordinate of scaling origin 

2(int) y-coordinate of scaling origin 
8(real)x-scaling factor 
8(real)y-scaling factor 
l(int) Current hardware (BIOS) screen: 



0, 1 


40 X 25 text 


cga,text,raedium 


4,5 


320x200 graph 4 color 


cga,graphics,medium 


6 


640x200 graph 2 color 


cga,graphics,high 


7 


80 X 25 mono text 


mda 


13 


320x200 graph 16 color 


ega,graphics,low 


14 


640x200 graph 16 color 


ega,graphics,medium 


16 


640x350 graph 16 color 


ega,graphics,high 


17 


640x480 graph 2 color 


mcga.graphics.high 


18 


640x480 graph 16 color 


vga,graphics,medium 
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zscreenc 



zscreenh 



10 zscreenm 



zscreenr 



zscreent 



20 



zsdisks 



zserial 
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19 320x200 graph 256 color mcga,graphics,medium ^ 
l(int) Current screen color type, as selected with the -screen- conmiand: 0 = 
color; 1 = mono 

l(int) Screen hardware driver (*.DIS file); adjusted for display hardware actually 
detected: 

0 cga lOvga 

2 hercules 1 1 mega 

3 ega 4 evga 
9 att 

l(int) Current screen mode, as selected with the -screen- command: 0 = 
graphics, 1 = text 

l(int) Current screen resolution, as selected with the -screen- command: 

0 low 2 high 

1 medium 3 altl 

4 alt2 5 alt3 

l(int) Current screen type, as selected with the -screen- command: 

0 cga 5 ncr 10 vga 

1 tecmar 6(reserved) 1 1 mega 

2 hercules 7(reserved) 12 online 

3 ega 8 nokia 13 (reserved) 

4 (reserved)9 atf 14 evga 

4(bits)Bitmap of drives to include in automatic searches, set in DOS by SET 
TCSEARCH= 

8(alpha)8-character serial number of TenCORE executor 
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zsetret 



Z5pace 
zsysver 
ztelmain 
ztmmain 
10 ztmunit 
zuncover 
zunit 
zvarsi 
zwidth 

15 

zwindows 
zwindowx 
zwindowy 
zwpage 
20 zx 

zxmax 
zxycolor 
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1 (int) Kind of match found when -setname- is executed; possible values ^re: 

N Unique partial match (N-I chars) 

-1 Exact match; a name is selected 

0 No match; selection cleared, no name selected 

+N Non-unique partial match (N chars); first partially matching name selected 

2(int) Current character column 

4(alpha)TenC0RE version in the form "X.XX" 

4(int) Elapsed time spent in previous main unit 

4(int) System clock at start of main unit 

4(int) System clock at start of current unit 

2(int) Current uncover key as set by uncover command 

8alpha)Unit name of current unit 

4(int) Total size of global variables, in bytes 

l(int) Width of graphics lines set by -width-; affects draw, circle, ellipse, 
polygon, and dot 

2(int) Number of windows opened (besides initial window 
2(int) Absolute x-coord of lower left corner of window 
2(int) Absolute y-coord of lower left corner of window 
l(int) Display write page set by -page 
2(int) Current graphic horizontal location 
2(int) Maximum x-coordinate in current window 
2(int) Color of dot at current screen location 
In text mode, foreground color of character 
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zy 2(int) Current graphic venicai location ^ 

zymax 2(int) Maximum y-coordinate in current window 

Displaying the Contents of Variables 
Displaying Numeric Variables 
5 Variables which contain numeric information can be displayed using the show command: 

at 17:21 
show ztriea 

The normal form is show varname where varname is the name of the variable to display. 
For integers, show displays the first non-zero digit at the current screen location and 
10 displays up to 20 digits. For real numbers, it starts at the current screen location and displays up 
to 24 places, including a decimal point and three decimal places. This can be altered by adding 
field and right tags, as in: 

show reals, 2, 6 

which displays up to a total of twelve places (including the decimal point): six digits including 
15 trailing zeros are displayed to the right of the decimal point. In this case, if the value of "real8" is 
1.2345, it displays: 

1,234500 

(t. starting screen location) 

Tabular Display 

20 A second form of displaying numeric information, showt, right-justifies and space-fills the 

field when it displays a variable. This is useful for aligning columns of numbers. For example: 

define local 

varl / 8 / 3: 

vax2 , 8 , r 

25 var3 , 8 , r 
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var4 


,8,r 


define 


end 


set 


varl 


at 


5:5 


showt 


varl ,12,4 


at 


6:5 


showt 


var,^ , 1^ , 4 


at 


7:5 


showt 


var3 ,12,4 


at 


8:5 


showt 


var4,12,4 



1.1, 20.02, 300.003, 4000.0004 



The code above produces output similar to this: 



1 . 1000 
20.0200 
300.0030 
4000 . 0004 



Hexadecimal Display 

The showh command displays the contents of a variable using two hexadecimal base* 16 
digits for each byte of the variable. For example: 

25 calc int4 c= 32766 

showh int4 
displays: 

00007ffe 
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Unless the optional length tag is specified, showh displays as many digits as necessary to 
show the entire variable (2 digits for a one-byte variable; 4 digits for a two-byte variable; etc.). 
Alphanumeric Display 

Text information is usually displayed using the showa (for "show alphanumeric") 
5 command. 

packz textbuf ; ; Good morning ! 
at 5:5 

showa textbuf $$ displays Good morning" 

The showa command displays characters for the length of the variable or for an optionally 
10 specified length. 

showa textbuf ,6 $$ displays "Good m" 

Embedded show 

In practice, the show command and its variants are usually embedded in a write 
command, as in: 

15 at 5:5 

write «show^reail» «s,reall» $$ 's' is for (s) how 

«showt , reall» «t,reall» $$ *t' for show (t) 

«showh , reall» «h,reall» $$ *h' for show (h) 

«showa,text» «a,text» $$ 'a' for show (a) 

20 Note that the abbreviations s, /, h, and a can also be used. 

The characters « and » are called embed symbols. The left embedding symbol is produced 
by pressing [ALT][<], the right embed symbol is produced by pressing [ALT][>] 
The general form for embedding a show command in a write is: 
«command,expression» 

25 Command is one of the show commands or its abbreviation; expression may be a number, 

a variable, or a calculation involving either, as in: 
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write The Fahrenheit temperature is «s , 9*celsius/5+32» . ^ 

Assigning Values to Variables 

Assigning values to variables is performed in various ways depending on the type of 
variable and the type of information to be stored in the variable. 
5 Numeric Values 

Values are assigned to numeric variables using the calc command: 

define local 

ratio , 4 , real 

define end 

0 

calc ratio 1 / 3 

The general form of calc is: 
calc variable <= expression 

variable any author-defined numeric variable 
5 c= the assig?iment arrow (produced by pressing [ALT] [A] is the operator 

that assigns a value to the variable 
expression a valid arithmetic and/or logical expression 
In the example above, TenCORE calculates the value of 1 divided by 3 and stores it into 
the variable 'ratio', 

0 The caic command can be continued from one line to the next, as follows: 

calc a c= 1 

b c= 2 
c c= b / 3 
d c= c + b 
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The calc command above assigns values to four different variables without the necessity 
of repeating the command name on each line- 
When a real value is assigned to an integer variable, the value is rounded to the nearest 

integer. 

5 The calc command works only with valid numeric variables (i.e., 1,-2-, 3-, 4-, and 8-byte 

integers, and 4- and 8-byte reals). It does not work with 5-, 6-, or 7-byte variables, or with any 
variable larger than 8 bytes. 

The flill range of arithmetic and logical operators which can be used with calc, as well as 
alternate ways of representating numeric values, are treated in the section Ways of Representing 
1 0 Literal Data later in this chapter. 
Selective Forms 

The calc command has two selective forms, calcc and calcs. For more information, see 
the respective command descriptions. 
Text Values 

1 5 Because the calc command works only with numeric variables, i.e. variables with a 

defined length of 1, 2, 3, 4 or 8 bytes, it is not suitable for assigning text to variables. 
Text is assigned to variables using the packz command. Its general form is: 
packz buffer; [ length ]; text 

buffer the buffer to receive the text 
20 length an optional tag a variable to receive the number of charcters assigned to 

variable (the packz command sets length, not the author) 
text the text information to assign to variable 
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The "z" on packz indicates that any bytes oUiiffer not used to store the text are zero 
filled. Without zeroing, packing ^'rose'^ into a buffer which already contained "geranium" would 
give "rosenium'\ If zero filling is not desired, use the pack command. 

define local 
sublen,2 
siibject , 40 
define end 
* 

packz sxibject , sublen; Geography 101 



at 5:5 

write The heading «a,subject» is «s,sublen» bytes long. 

The length tag can be omitted, leaving two adjacent semicolons between the variable and 
the text to be assigned: 

15 packz siobject; /Geography 101 
♦ 

at 5:5 

write The heading is «a ; sub ject» . 

Like the write command, packz can be continued over several lines: 

20 packz text2;;This is line one. 

This is line two. 
This is line three. 

Any of the show commands can be embedded in the text tag of the packz command just 
as they can be embedded in a write command: 

25 packz text ;textlen; atomic weight of «a,element» is «s,weight». 
at 5:5 
show text 
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When showa is embedded in a packz command, null characters( bytes with a value^f 0) 
in the embedded variable are skipped over instead of being copied. If a special application 
requires that even the null characters be copied, the showv command can be used instead of 
showa. The showv command works just like showa with the important exception that even null 
5 characters are copied in a packz command or displayed in a write command. 

The showv command has both an embedded form (abbreviated <(v, ») and a non- 
embedded form, but is is primarily intended for embedding in a packz command. 
Selective Form 

The packz command has a selective form called packzc. For more information, see the 
10 respective command descriptions. 
Copying Non-numeric data 

The easiest way to copy non-numeric data from one variable to another is to use the 
move command, which has the general form: 
move source, destination, length 

15 source any defined variable or a literal 

destination any defined variable 

length an expression specifying the number of bytes to move. 

The following example copies the contents of the 40-byte variable "newname ' into the 
variable ''oldname*\ 

20 move newname , oldname , 40 

Converting Text to Numbers 

The compute command translates a string of numeric characters into a numeric value. 

' pack text;textl;-12345 
coirpute text , textl , result 
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at 1:1 

show result 

The general form is 
compute buffer, length, result 
5 ^ buffer the string of characters 

length the number of characters to convert 
result the variable in which to store the result 
The string to be convened can contain: 

• the digits 0 through 9 

10 .the unary and - characters (the positive or nesative sign) 

• one decimal point (period) 

Any other characters within the string cause compute to fail, indicated by a zreturn value 
greater than -1 . If it fails, compute makes no changes to the value stored in "result". 

For extracting numeric information from the input at an arrow, see the store and storen 
15 command descriptions. 

Initialization of Variables 

Author-defined global variables should normally be initialized before use. This is often 
accomplished in a program's startup unit using the zero command, 
zero 

20 The simplest form of zero sets a single variable to zero, whatever its defined length; 

zero usernarne 

Another form of zero clears a specified number of bytes starting at the named variable. 

^zero scores, 22 

Here, it zeros 22 bytes starting at "scores". The general form for clearing a number of 
25 bytes is: 
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zero variablejength 

variable name of the variable at which to start 
length the number of bytes to zero 
Startup units often clear all of global variable space before assigning any values to 
5 variables. This ensures that the lesson has a clean slate to work with. 

For clearing global variable space,, the system variable zvarsl gives the total number of 
bytes reserved for storage of global variables (including space which has not been defined). If 
"firstvar" is the first global variable defined, the following command zeroes all global variables: 

zero firstvar, zvarsl 

10 If "firstvar" is not the first global variable defined, an area zvarsl bytes in length would 

extend beyond the end of global variable space. In this case, the zero command above results in 
an execution error. 

Local variables do not need to be explicitly set to zero. All of a unit's local variables are 
automatically zeroed when execution of the unit begins, 
15 set 

Another way of initializing variables is with the set command. Rather than zeroing 
variables, set assigns a series of values to consecutive variables: 

define local 
jan / 1 

20 feb ,1 

$$ all twelve months 

nov 1 1 

dec 1 1 

25 define end 
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set jan <= 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 

This example assigns 3 1 to ^>n", 28 to "feb" and so on. It has the same effect as twelve 
calc commands. 

The normal form of the tag is: 
set variable value list 

variable the variable to assign the first value to. 
value list the subsequent values that are assigned to locations 

following variable. 

The set command does not perform any bounds checking; assignments are made based on 
the defined length of the variable named in the tag, regardless of how the subsequent variables are 
defined. In the above example, "jan" is defined as a 1-byte integer, so the values in the tag of the 
set are assigned to the twelve bytes staning at ^'jan If the eleven variables defined immediately 
following "jan" are not all 1 byte long, they will not contain the expected values. 

The set command has a selective form setc. For more information, see the respective 
command descriptions. 
Comparison and Searching 

Two variables can be compared using the compare command. This command returns the 
number of leading characters which match in the two comparison strings. 

define local 
,stringl,26 
string2 ,26 
result, 1 
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define end 



pack stringl; ;abcdef ghi jklmnopqrstuvwxyz 

. pack string2 ; ;abcDEFGHIJKLMNOPQRSTUVWXY2 

5 con^jare stringl , string2 , 26 , result 

This example compares '^stringl" to "stringZ" and sets "result'* to the number of leading 
characters which matched; in this case 3, for 'abc'. 

The general form of the compare command is: 
compare varl,var2,length,result 
10 varl one of the variables to compare 

var2 the other variable to compare 
length the number of bvles to compare 

result set to the position of the last matching byte. It is set to - 1 if varl and 
varl are identical or 0 if they do not match at all 

15 find 

Variables can be searched for specific contents using the find command. 

define local 
alphaOaet, 26 
aiphalen, 2 
20 location, 2 

pack z alphabe t ; aiphalen ; abcdef ghi j klmnopqr s tuvwxy z 



find ^ef , 2 , alphahet , aiphalen , 1 , location 

This example searches the variable 'alphabet" for the string 'ef. It finds it and sets the 
25 variable "location" to 5 because 'ef starts at the fifth byte in the search area. 
The general form of the find command is: 
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find object, object-length, start-var, list-len, incr, location ^ 

object the value to search for. This can be a literal, a variable, or a buffer 
object-length the length of the object to search for, in bytes, 
start-var the variable at which to start the search 

5 list-len the number of entries to search. An entry can be more than 

one byte long, as specified by incr 
incr the length of each entry. 

location the entry number at which object was found If object was 

not found, location is set to -1. 

10 Examples 

The following examples assume definition of the following variables: 

define local 

name ,15 $$ name to search for 

found ,2 $$ position in list where "name" found 

15 list (5) , 15 $$ list of names 
define end 

The variable "list" contains a list of 5 names, each of which occupies 15 characters. The 
contents of "list" are as follows; 

john miller... mark ho sarah johnston.james heflin lisa berger 

20 tl tl6 131 146 161 

Null characters have been shown as to improve their visibility, and numbers have been 
added to help in counting bytes. 
Literal Object 

The following find statement searches for the name mark ho: 

25 find ^markho' ,7, list (1) ,5, 15, found $$ found will be 2 
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Because the name has fewer than 9 characters, it can be supplied as the text literal '-mark 
ho'. Next comes the length of the object to find, 7 characters. The start of the list is given as 
list(^y/ and its length as 5 entries of 15 bytes each. 

After the search, the variable "found" contains the value 2 because mark ho is found at 
5 the second position (not the second byte) in the list. 
Variable Object 

Since names of more than 8 bytes cannot occur as text literals, they must be packed into 
variables. The following example locates James heflht 

packz name ; ; james heflin 
10 find name, 15, list (1) ,5, 15, found 

The variable "found" receives the value 4 because James heflin is found in the fourth 
position. 

Byte-by-byte 

To find a last name, a find like the following could be executed: 

15 packz name ;; miller 

find name , 6 , list (1) ,75,1, found 

When this example is executed, "found'' receives the value 6. 

The length of the name is given as 6 because this locates part of an entry, not an entire 

entry. 

20 Similarly, the list is specified as 75 one-byte entries instead of 5 fifteen-byte entries. This 

causes find to look for miller starting at every character, not just at the start of each 15-byte 
name field. This illustrates that the object of the search can be longer than the nominal entry 
^ length provided to find. 
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Backwards by Entry ^ 

To search backwards, a negative value is given for the increment. The following example 
searches backwards from the end of the list for johfi looking only at the beginning of each 15- 
byte entry: 

5 find ' john' ,4,list(l) ,5, -15, found 

Here, 'Tound" receives the value 1. Although the search proceeded backwards from the 
end of the list, the position is always counted from the beginning of the list. 
Backwards by Byte 

.\nother example of backwards searching is the following: 

10 find ^john' ,4,list(l) ,75,-1, found 

In this case, an increment of-1 is used, causing fmd to look at every character starting 
from the end of the list. 

In this case, "found" receives the value 37, because the first john found when searching 
backwards byte-by-byte occurs in sarah Johnston, If the search had been in the forward direction. 
1 5 john miller would have been found first, and "found" would have received the value 1 . 
Ways of Representing Literal Data 

Data used in calc commands and other numeric contexts can be expressed in a number of 
literal forms. 

For purposes of discussion, the term Uteral is used to identify a 1-, 2-, 3-, 4- or 8-byte 
20 value which is expressed directly rather than as a variable or an expression. Values of 5, 6 or 7 
bytes can be used as literals, but are represented internally as 8-byte values. 
Integer Literals 

Any valid number written as a sequence of digits with no decimal point is an integer 
literal. An integer literal may have a leading plus or minus sign. 
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Real Literals ^ 

A real literal is distinguished from an integer literal by the presence of a decimal point. 
Even if there are no digits following the decimal point, the presence of the decimal point causes 
the value to be represented as a real value. 
5 Text Literals 

A text literal is a string of 1 to 8 characters enclosed in single quotation marks. Many 
commands allow file names, unit names or other block names to be written as text literals: 

image plo t ; ' pictures ' , ' bird' 

The image command above displays a screen image stored in file pictures, block bird. 
10 Text literals are always stored internally as 8 bytes; unused b>tes at the right end of the 

text are zeroed. Another way of stating this is that text literals are stored left-justified in 8 bytes. 

Because text literals are 8 bytes long, the calc command can be used to assign a text 
literal to an 8-byte variable: 

calc filename <:= 'pictures' 

15 The variable must have been defined to be 8 bytes long. If a shorter variable is used, 

characters are certain to be lost from the beginning of the text literal. 
Character Literals 

Character literals normally consist of a single character enclosed in double quotation 

marks: 

20 if name (2) = ^^a" 

Such a character literal is stored internally as a single byte. 

A character literal can be assigned directly to an integer-compatible variable using caic: 

' calc name(2) c= ^^z" 

It is also possible, although unusual, to create multiple-byte character literals by enclosing 
25 a string of 2 to 8 characters in double quotes: 
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calc chars c= "ahc" 

Such a literal is always stored in the smallest possible of 1, 2, 3, 4 or 8 bytes. If the literal 
contains 5, 6 or 7 characters, zero-valued bytes are added to the left end of the literal to round i 
length up to 8 bytes. Another way of saying this is that character literals are stored right-justifled 
in the smallest possible size of I, 2, 3, 4 or 8 bytes. 

Multi-byte character literals (enclosed in double quotes) are not a substitute for text 
literals (enclosed in single quotes). Correct usage is to use single quotes for all textual literals 
such as file names and unit names, and to reserve double quotes for single characters. 
Keypress Literals 

When examining the system-defined variable zinput, which reports the last key processed, 
one often uses keypress literals. 

A keypress literal is normally a 1-byte character literal prefixed with a percent sign as 
follows: %"a". The percent sign changes the 1-byte character literal into a 2-byte internal 
representation consistent with zinput. 

A number of other prefixes exist as well; %alt, %ctl, %altctl and %ctlalt (the last two are 
equivalent). Thus, to determine whether the last key processed was [CTRL][A] one could write 

if zinput = %ctl"a" 

All keypress literals are represented internally as two byte positive values. The detailed 
format can be found under the description of zinput. 
20 Hexadecimal Literals 

This discussion of hexadecimal (base 16) literals should be considered optional advanced 
material. If you have not used hexadecimal numbers before, you probably do not need this 
'information and you may want to skip ahead to Constants. 
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A hexadecimal literal is written as the letter h followed by a digit 0 - 9, followed by^ero 
or more of the hexadecimal digits 0 - 9 and a -/(In hexadecimal notation, the values 10 through 
1 5 are represented by the leners a through /) 

Thus the following are valid hexadecimal literals: 



h4 (equals decimal 4) 

hlO (equals decimal 16) 

hOf (equals decimal 15) 

hlec4 (equals decimal 7876) 

hffff (equals decimal -1) 



Note that hf would not be a valid hexadecimal literal, since the first digit after h must be 
within the range 0-9. .\ny time the first digit of the hexadecimal value is one of a through /, an 
extra 0 must appear after the h as in: hOf. 

It is useful to think of hexadecimal literals as being evaluated "backwards", from right to 
left. The digits of the literal are read in pairs, starting from the right, and each pair of digits 
corresponds to one byte in the internal representation of the value. Each new pair of digits causes 
a new byte to be added to the internal representation of the literal. A lone, unpaired digit 
remaining at the left end of the literal also causes another byte to be added, unless the remaining 
digit is zero. A lone, unpaired zero at the left end of the literal is always discarded. If the resulting 
internal representation is 5, 6 or 7 bytes long, zero-valued bvtes are added to the left of the value 
to pad it out to 8 bytes. 

Hexadecimal Literals as Integer Values 

In calculations, a hexadecimal literal is always considered an integer value, .When 
assigning a hexadecimal literal to a variable, it is important to distinguish between the length of 
the variable and the length of the literal. Consider the following example: 

define local 
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end 



calc temp <= h91 

5 Here the value of a 1 -byte literal is assigned to a 4-byte integer variable. The integer value 

of the literal is evaluated before considering the length of the variable. Since the literal is one byte 
long, its value is h91, which corresponds to the binary value 10010001. Because the leftmost bit 
is a ' r, the value is interpreted as a negative number: 111. This is the value assigned to the 
variable "temp". Note that the two-byte literal h0091 or the four-byte literal h00000091 would 
10 have given a different result, namely the positive number 145. This is why it is important to pay 
attention to the length of a hexadecimal literal. 
Hexadecimal Literals as Bit Patterns 

It is sometimes desirable to use a hexadecimal literal to assign a particular pattern of bits 
to a real variable. This cannot be done using calc, because a calculation would interpret the 
1 5 hexadecimal literal as an integer, and then convert the value of the integer to the IEEE format 
used to store real numbers in TenCORE. The numeric value would be preserved, but the bit 
pattern would not. 

The move command can be used to copy a hexadecimal literal into a variable as a bit 
pattern without any numeric interpretation: 



20 



define local 
height, 4, real 
define end 



25 



move 



h7f 800000, height, 4 
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This example copies the 4-byte bit pattern for the indefinite value 1/0 into the 4-byte real 
variable ''height". Because no calculation is performed, no conversion of the bit pattern takes 
place. 

Constants 

5 A constant is a named item of literal data. Constants can be defined globally or locally 

using the = sign: 

a=l 

greet=' Hello' 

The general syntax for constant definition is name^literal. A constant can be given any 
10 name which is valid for a variable. Constant definitions can occur at any point where a variable 
definition can occur. Once defined, a constant can be used anywhere that the literal data it 
represents could be used: 

define local 
Picf ile=' pictures' 
15 picbiock=' f ish' 
Px=:140 
Py=100 
define end 
* 

20 image plot ;block , Picf ile ; Picblock ;Px , Py 

The image command above is equivalent to: 

image plot ;block, 'pictures' , ' f ish' ; 140, 100 

Constants are often defined for use in defining other variables: 

MAXNAMES=20 
25 naine (MAXNAMES) ,20 
age (MAXNAMES) ,2 
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address (MAXNAMES) ,40 ^ 

This example defines three arrays of length 20. The lengths of all three arrays can be 
changed by changing the definition of MAXNAMES, 

Many programmers make a convention of using upper-case characters for names of 
5 constants so they are not easily confused with variable names. 

The same rules apply to literals used in constant definitions as to literals used anywhere 
else. A constant has a value, a type (integer or real), and a length (the number of bytes in the 
internal representation). As with other literal data, all three of these characteristics must 
sometimes be considered when using a constant in a calculation. 
10 Operators 

TenCORE supports a rich variety of operators which can be used to combine literals, 
constants and variables into numeric expressions. In addition, TenCORE supports a number of 
mathematical functions and provides a mechanism for the author to define other functions. 



Arithmetic Operators 



15 



Addition 



Assignment (e.g., a cz b means assign b value to a) [CTRL] [C] [A] or 



[ALT][A] 



Subtraction 



* or X Multiplication, real arithmetic [CTRL][C][+] 



20 



SimulS Multiplication, integer arithmefic 



Division, real arithmetic {CTRL][C][/] 



SidivS Division, integer arithmetic 



Exponent (e.g., a ** b means a to the b power) 



0 



Convert preceding value from degrees to radians [CTRL][C][°] 
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Logical Operators ^ 
Logical operators compare expressions and return values corresponding to true or false. 
For example, the command sequence: 

if 2 < 3 

5 . write True 

endif 

plots True because 2 is less than 3. This is similar to posing the question: 
True or false: Two is less than three. 

Logical operators compare the operands in an expression and then return value - 1 if the 
10 expression is true, 0 if false. Key sequences used to enter non-standard characters are shown. 
= Equal to (true if operands are idenfical) 

^ Not equal to (true if operands are not identical) 

< Less than (true if leti operand is less than right operand) 

> Greater than (true if left operand is greater than right operand) 

15 < Less than or equal to (true if left operand is less than or equal to right 

operand) 

> Greater than or equal to (true if left operand is greater than or equal to 
right operand) 

SandS Logical "and" (true if both operands are true 

20 SorS Logical "or" (true if either operand is true) 

In addition to the operators above, the notQ function returns true if the operand in 
parentheses is false and vice versa. 

The operands of a logical operator do not have to be numeric values; for example, ASCII 
characters can be compared with each other. 



3NSDOCID <WO 9907007A2_I 



wo 99/07007 PCT/US98/15627 

145 

In TenCORE, true is represented by a value of -1 and false is represented by a value of 0. 
For example, some expressions and their numeric values are: 

2 < 3 $$ returns -1, true 

2 = 3 $$ returns 0, false 

5 2 > 3 $$ returns 0, false 

not( 2 > 3 ) $$ returns -I, true (true is the sane as not false) 

More generally, TenCORE treats any negative value as true and any non-negative value 

as false. 

Because true and false have associated numeric values, a logical expression is often used 
10 as the selector in the selective form of a command: 

writec 2<3 , -True ; False 

This example prints True because 2 is less than 3 and the result of the expression is thus - 
1; had the expression been false, the numeric value would have been 0 and the example would 
have printed False. 

1 5 Although logical operators are normally used in combination with each other, they are 

occasionally used together with arithmetic operators as in the following: 

calc score c= score - (annwer=correct) 

* increments "score" by 1 if answer=correct 

This has the effect of leaving "score" unchanged if the values of "answer" and "correct" 
20 are different. This is because the value of ans^ver=correct will be False (0), and the value 
assigned to "score" is score - (0). But if the values of "answer" and "correct" are equal, then 
answer=correct has the value True (-1) and the value assigned to "score" is score -(-1), which is 
equivalent to score + /. 
Bitwise Operators 

25 Bitwise operators treat each operand as a pattern of bits rather than as a numeric value. 
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The bitwise operators and the operations they perform are: ^ 
SmaskS Logical "and". Each bit in the result is set if the corresponding bit is set in 

both operands 

Logical "or". Each bit in the result is set if the corresponding bit is set in 
either operand. 

Logical "exclusive or". Each bit in the result is set if the corresponding bit 

is set in one of the operands and not set in the other operand. 
Arithmetic Right Shift. The bit pattern in the first operand is shifted right 
by the number of places given in the second operand. The leftmost 
(sign) bit propagates to the right, and bits which "fall ofF the right end 
are discarded. 

Circular Left Shift in 1 byte. The bit pattern in the first operand is 

circularly shifted leftwards for the number of places given in the second 
operand. Bits shifted out of the left end of the byte re-appear in the 
right end. 

$cls2S Circular Left Shift in 2 bytes. 

$cls3$ Circular Left Shift in 3 bytes. 

Scls4$ Circular Left Shift in 4 bytes. 

SclsSS Circular Left Shift in 8 bytes. 

For example, SmaskS, SunionS and SdiffS produce the following results: 

$mask$ $union$ $diff$ 
45 00101101 00101101 00101101 

84 01010100 01010100 01010100 



SclslS 
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121 00000100 01111101 01111001 

Thus 45 SmaskS 84 equals 4; 45 SunionS 84 equals 125; and 45 SdiffS 84 equals 121. 

Bitwise operators are intended to operate only on integer values and non-numeric values 
with valid integer sizes (1 ,2 ,3 ,4 or 8 bytes). They are not suited for use with real values. 
System-Defined Functions 

TenCORE supports a number of system-defined functions which take an argument in 
parentheses. These include trigonometric, logarithmic, logical, arithmetic and address functions. 
Logarithmic 

Antilogarithm base 10 of x (10 to the power) 
Math constant C to the x'*" power 
Natural logarithm of x 
Logarithm base 10 ofx 
Logarithm base n of x 



alog(x) 
10 exp(x) 
ln(x) 
log(x) 
logx(n,x) 
Negation 
1 5 comp(x) 

not(x) 
Trigonometric 

acos(x) 
20 asin(x) 
atan(x) 
cos(x) 
sin(x) 
tan(x) 



Bitwise complementation. All bits in operand x are inverted (bits 
containing ' T are reset to 0' and vice versa). 

Logical negation. Returns taie (-1) if operand xis false and vice versa. 

Arc cosine (x in radians) 
Arc sine (x in radians) 
Arc tangent (x in radians) 
Cosine (x in radians) 
Sine (x in radians) 
Tangent (x in radians) 



BNSOOCID; <WO 9907007 A2 ,t_> 



wo 99/07007 PCT/US98/15627 

148 

Address 

absloc(v) 4-byte absolute address in memory of variable v 

sysloc(global) Segment address of global variable space 

sysloc(local) Segment address of local variable space for current unit 

5 varloc(v) Offset from start of local or global variable space for variable v 

Arithmetic 

abs(x) Absolute value of x 

bit(v,x) Logical value of bit x in variable v (-1 if the bit is 1) 

bitcnt(v,n) Number of bits set in variable or buffer V, in a range of n bits 

1 0 frac(x) Fractional part of x 

imod(x,y) x modulo y 

int(x) Integer pan of variable x 

mod(x,y) x modulo y 

randi(x) Random integer from 1 to x 

1 5 randi(x,y) Random integer from x to y 

randr(x) Random real value from 0.0 to x 
randr(x,y) Random real value from x to y 

round(x) x rounded to the closest even integer 

sign(x) - 1 if X is negative 

20 0 if variable x is positive 

sqrt(x) Square root of x 

7C Pi(3. 141592653589793 12) [CTRL][C][P] 
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Evaluation of Expressions 

This section discusses the details of how TenCORE evaluates expressions. The first part. 
Precedence of Operators, is useful to all authors. The remainder of the material can be regarded 
as optional information for authors who need to optimize calculations for maximum possible 
5 efficiency of execution. 

Precedence of Operators and Functions 

TenCORE observes a cenain precedence of operators in evaluating expressions. Thus the 
expression 5 + 4*3 equals 17 instead of 27 because the multiplication operator * has a higher 
precedence than the addition operator +. and is executed first. This makes the expression 5 + 12 
10 instead of9* 3 

Parentheses override the normal order; operations within the parentheses are done first (in 
normal order). The resulting value is then used in the related operation in the expression. The 
following table shows the TenCORE operators and functions in the order in which they are 
performed. Class I is performed before class 2, 2 before 3, and so on. 
' 5 1 Exponentiation (**) and Functions 

2 Unary Minus and Unary Plus 

3 Multiplication and Division (*, /, SimulS, SidivS) 

4 Addition and Subtraction (+, -) 

5 Bitwise Operators (SunionS, SmaskS, SdiffS, 
20 SarsS, SclslS, $cls2S, $cls3S, $cls4S, $ds8S) 

6 Comparison Operators (= ^, <,>, < ,>) 

7 Logical Operators ($and$, $or$) 

8 Degree-to-Radian Conversion (° as in 45°) 
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9 Assignment (cr) ^ 

Rounding 

Rounding of a value with a fractional part exactly equal to .5 always yields an even 
integer Another way of stating this is that values where the fractional part is .5: 
5 • round up if the integer part is odd 

• round down if the integer part is even 
Example 

calc intvar c= 7.5 $$ "intvar" assigned the value 8 

intvar c= 8 . 5 $$ "intvar" assigned the value 8 

1 0 Compression of Sub-Expressions 

Some sub-expressions are evaluated and compressed when a unit is translated to binary 
form rather than when it is executed: 

calc ratio c= (4 + 5) / limit 

Because the sub-expression (4+5) contains only integers and its value is known already 
1 5 before the program is run, the command would be represented internally as: 

calc ratio c= 9 / limit 

To qualify for evaluation and compression at translation time, a sub-expression must 
contain only: 

• integer literals which fit in 4 bytes or less 
20 • integer constants which fit in 4 bytes or less 

• the operators + - Simuls SidivS 

Sub-expressions containing other elements cannot be evaluated at condense time and are 
'not compressed. 
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Operator Types ^ 

Certain operators and functions work exclusively on a particular type of value, either real 
or integer. Non-conforming values are internally converted into the type expected by the operator 
or function before any operation is performed. 
5 Operators which work with real values are: 

* real multiplication 

/ real division 

** exponentiation 

degree-to-radian conversion 
10 In addition, the trigonometric functions, exponential and logarithmic functions, and intQ, 

fracQ and roundQ always work with real values. 

When these operators and functions are used with integer operands, the operands are first 
converted to real values. If the result is assigned to an integer variable or used in a command 
which expects an integer value, the resuh is convened to back to integer. 
1 5 Operators which work only with integer values are: 

SimulS integer multiplication 
SidivS integer division 

In addition, the logical and bitwise operators, and the ftinctions imodQ, notQ and comp(), 
always work with integer values. 
20 When these operators and functions are used with real operands, the operands are first 

converted to integer values. If the result is assigned to a real variable, it is converted to real 
before assignment. 

Other operators and functions can work on real or integer values and do not perform any 
internal conversions. 
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Operator types normally affect only a program's speed of execution. However, certain 
integer operators applied to real values may give unexpected results if the implicit conversion is 
not kept in mind. The bitwise operators in particular, together with the compQ function, don't 
really give meaningful results when applied to real values. 
Intermediate Values and Speed Optimization 

A TenCORE author usually does not need to know how intermediate values used in 
evaluating expressions are represented internally, as the internal representation does not affect the 
correctness of the result. However, the information can be useful in optimizing calculations for 
speed. 

Intermediate values are always represented as either 4-byte integers or extended-precision 
10-byte reals. Four-byte integers are used if all three of the following conditions are met: 

• none of the operands are real 

• none of the operators require real values 

• none of the operands are longer than 4 bytes 

If any of the above conditions are not met, 10-byte reals are used. Since lO-byte real 
calculations take several times as long as 4-byte integer calculations, a single real operand in an 
otherwise (4-byte) integer expression can significantly slow down its evaluation. In practice, this 
is usually significant only in particularly speed-critical applications, especially if a math 
coprocesor is not present. 

Author- Defined Functions 

An author-defined function is a named expression. Like constants, functions are defined 
using the = sign: 

pressure = weight / area 
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The simplest syntax for function definition is name^expression. A function can ha^ any 
name which is valid for a variable. Function definitions can occur at any point where a variable 
definition can occur. Once defined, a function can be used anywhere that the expression it 
represents could be used. 
5 Arguments 

Functions can be defined with arguments: 

fahr(xx) = 9 * xx / 5 + 32 

inrange (aa,bb,cc) = aa ^ bb $and$ bb <, cc 

The function 'TahrQ" defined above gives the Fahrenheit equivalent of a Celsius 
10 temperature. It could be used as follows: 

write 15° celsius is «s,fahr(15)» Fahrenheit 

The fiinction "inrangeO" determines whether one value lies between two others, returning 
true or false. It could be used as follows: 

inrange(100,2inputx,200) $and$ inrange ( 140 , zinputy , 180) 
1^ * write Good! You pointed inside the box. 

endif 

This example checks whether the last pointer input (given by the system variables 
zinputx,zinputy) was within a rectangular area with opposite corners at 100,140 and 200,180. 

The general syntax for defining a fijnction with arguments is 
20 name(argl,arg2, ..,,zxgn)=expression 

An argument can have any name which is valid for a variable, but must not duplicate the 
name of a variable which is already defined. Many authors use double letters such as aa, bb, etc., 
to minimize the likelihood of using an argument name which conflicts with a variable or constant 
name. 
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The purpose of author-defined functions is to improve readability of source code aad to 
simplify changes. When a program is translated to binary form, each reference to a function is 
expanded to the full length of the definition. Using functions thus has no effect on the final size or 
efficiency of a program. 

Reduction to Constants 

Any integer-valued Sanction which can be entirely evaluated and compressed at condense 
time is reduced to a constant (see the Compression of Sub-Expressions section earlier in this 
chapter). Thus the following two definitions are equivalent: 

length = 4 + 256 + 128 



10 



length =38 8 

Reduction of simple functions to constants is panicularly useful when defining variables, 
as it makes possible constructions like the following: 

define local 
15 HSIADER = 4 
ENTRIES = 20 

LENGTH = HEADER + ENTRIES 
list (LENGTH) ,1 
define end 

20 Type and Length 

Like literals, constants, and variables, Sanctions have an associated type and length. These 
are determined according to the rules given above for evaluating expressions. Thus the value of a 
function is always either a 4-byte integer or an 8-byte real. In practice, this is seldom significant, 
- since TenCORE automatically performs any needed type conversions. 
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Physical Allocation of Variable Space ^ 

In keeping with the differences in characteristics and usage between global and local 
variables discussed in chapter 4, they are stored in different physical segments of the computer 8 
memory. 

Global Variable Storage 

Global variables occupy a segment of memory which is reserved when TenCORE is 
started and is preserved until TenCORE is exited. There is only one segment of memory used for 
global storage. Every defines block and every define global statement allocates storage for 
variables starting at the beginning of this single segment. 

The system-defined variable zvarsl gives the length of the memory segment allotted for 
global variables. 

Local Variable Storage 

Local variables occupy a segment of memory specific to the unit in which they are 
defined. Each unit has its own separate local storage segment which exists only as long is the unit 
15 is active. This segment is reserved and zeroed when execution of the unit begins. When the unit is 
exited by branching to a new main unit, by reaching the end of the unit, or by exit via return or 
goto q), the space for that unit's local variables is released. 
Allocation of Space 

Within a set of global or local defines, successive bytes of storage are allocated 
20 sequentially starting from the beginning of the global or local segment. For example: 



10 



Defmtion 


Location(offset from start of segment) 


varl, 2 
var2, 2 
realvar^ 8, r 
userrame, 40 


Bytes 0 - 1 
Bytes 2 - 3 
Bytes 4- 11 
Bytes 12-51 



Two system-defined fiinctions return the location of a variable within memory: 
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varlocQ returns the offset within variable space (local or global) 



abslocQ returns the absolute location within computer memory 



The starting byte of each variable above could be displayed as follows: 



at 



5:5 



5 



write 



varl 



starts at byte «s , varloc (varl) » 



var2 



starts at byte «s , varloc (var2) » 



realvar starts at byte «s , varloc (realvar) » 



username starts at byte «s , varloc (buff er) » 



Bytes of storage can be skipped, as in: 

10 varl, 2 
var2 , 2 

where allocates four b\tes as unused. 
Absolute Definition 

1 5 Variables can be defined at an absolute offset (from the beginning of local or global space, 

as appropriate) by using the format: 
@offset, name, length, type 

where the @ symbol indicates that the variable is to start at the specified location. For 
example: 

20 (3 0, first,! $$ first byte of variable space 

GIOOO ,naitie, 8, i $$ 8-byte integer at offset 1000 

The variable "first" above could be used with zero to zero all global variables as follows: 

zero first, zvarsl 



25 block), the author guarantees that the zero command will always start with the first byte of global 



By defining "first" at an absolute location (rather than just placing it first in the defines 
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storage, even if other variable definitions are inadvertently inserted before "first" in the defines 
block. 

The offset for an absolutely defined variable may be given as a defined constant: 

loc = 2000 $$ defined constant 

5 @loc,xyz,r $$»xy2" starts at offset 2000 

The use of absolute definition does not affect the allocation of subsequent variables- 
allocation continues sequentially following the last variable which did not use absolute variable 
definition. 

Redefinition 

10 A technique very similar to absolute definition is redefinition, in which a variable is 

defined to start at the same location as a previously defined variable. Redefinition takes the 
format: 

@oldname, newname, bytes, type 

where the @ symbol indicates that the variable newname is to start at the same location 
15 oldname. For example: 

username,40 $$ full user name 

@usernajne,userchar,l $$ first character redefined/ 1-byte integer 

In this example, the variable "usercha" could be used with if to test whether the first 
character (and thus presumably the whole name) is null: 

20 if userchar = 0 

do get name 

endif 

As in the case of absolute definition, redefinition does not affect the allocation of 
subsequent variables: allocation continues sequentially following the last variable which did not 
25 use redefinition. 
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Segmentation ^ 

Variables may be broken down into smaller pieces or segments which can be referenced 
by name. 

define local 
5 systime ,4 

hours , 1 

minutes , 1 

seconds , 1 

hundr , 1 

10 define end 

clock systime 
at 3; 3 

write time: «s,hours» hrs , «s,minutes» min, «s,aeconds» sec 

15 With "systime" segmented as above, the bytes can be referenced collectively (as in the 

clock command) or individually (as in the write command). 

The definition of a segment must follow the definition of the variable of which it is a pan. 
A period must appear in the first position, then seven space characters (one tab), then the 
segment name and size. 

20 Segmentation is sometimes used in defining buffers for disk operations, which always use 

256-byte lengths of data. 

record, 256 

name, 40 

response ( 64) ,1 
25 * . score ,4 

time , 4 
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Here, "record" reserves a full 256 bytes, even though the segments only need 40 +-64 + 4, 
or 108, b\tes. This ensures that that one can read in a 256-byte disk record without affecting 
"time" or other neighboring variables. 

As this example illustrates, segments do not have to add up to the full size of the 
segmented variable. However, they normally must not exceed it. 

Only one level of indentation is allowed when defining segmented variables. If a segment 
needs to be further divided into sub-segments, this can be accomplished by combining 
segmentation and redefinition: 

userid, 20 

u.idl,10 
u . di V , 1 
u.id2,21 

★ 

@u.idl,,10 $$ redefinition of u.idl 

u.idl.a,! 
u.idl.b,9 

No name was given to the redefined variable. It could have been given a unique name 
such as "xuidl", but since the only purpose was to (sub-)segment "u.idl", it was simpler to omit 
the name. 

The use of period (.) in variable names has no special meaning in TenCORE, which treats 
the period just like any other valid character, but does give visual emphasis to the logical 
structure. 

Array Segmentation 

Segmentation of arrays is similar to segmentation of individual (scalar) variables. 
However, when an array is segmented, each segment is itself an array, even though no array size 
is given. 
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define local 
systime(3) ,4 
hours , 1 

minutes , 1 

5 . seconds , 1 

hundr , 1 

define end 
★ 

cl o ck sy s time ( 1 ) 

10 clock systiine(2) 
clock systimeO) 
★ 

write The three times are : 



15 «s,hours(l)» hrs , «s , minutes ( 1) » min, «s , seconds (1) » seconds 

«s.hours(2)» hrs, «s ,minutes (2) » min, «s , seconds (2) » seconds 
«s,hours{3)» hrs, «s , minutes (3 ) » min, «s , seconds (3) » seconds 

Because the variable "systime(3)" was defined as an array with 3 elements, each of the 
segments "hours", "niinutes", "seconds" and "hundr" is treated as an array which is referenced 
20 with an index in parentheses. 

Special Segmentation 

In certain cases, especially with anays, it is desirable to segment beyond the defined length 
of a variable. Normally, this would result in an error when the program is compiled before 
execution. However, by adding the keyword special (abbreviated s) after a segment definition, 
25 the check for segmenting beyond the length of the original variable is omitted. The defauhs for 
variable definitions cannot be used with this keyword: the length and type must be explicitly 
specified, with the keyword special added after the type, 
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Segmentation beyond the end of a variable does not cause any more bytes to be allOtated 
in variables, .\fter the special segments are defined, the next variable starts at the location after 
the last normally defined variable. 
Example 

5 Shows how one could define a data area containing mixed data types: two-byte integers 

and eight-byte integers. Each piece of data is prefixed by a single byte indicating which type of 
data follows. 

data, 8192 

@data,bufl (8192) ,1 
10 . typel,l,i,s $$ prefix byte 

datal,2,i,s $$ access 2 -byte words at any byte 
@data,buf2 (8192) ,1 

type2,l,i,s $$ prefix byte 

data2,8,i,s $$ access 8-byte words at any byte 
15 newvar,! $$ starts 8192 bytes after "data" 

$$ newar is overwritten by special segments 

By knowing the starting b\^e of an individual entry, the type can be determined and the 
appropriate variable name ("datal" or "data2") used to access the data in the appropriate format. 
The next entry would be found by incrementing the index into the array by the length of the 
20 current entry (3 or 9). 
Blocks 

A technique similar to segmentation but applicable on a larger scale is the variable block. 
Defining a variable block reserves a section of variable space. Within the variable block, scalar 
and array variables can be defined and segmented. 
25 The normal format for defining a variable block is: 
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name, size, block 

where name is any name valid for a variable; size is the number of bytes to reserve for the 
block; and block indicates that this is a variable block (block can be abbreviated as b). 
The following example defines a 255-byte block named "diskio": 

5 diskio, 256, block $S 25S-byte data area for disk input/ output 
,10 $$ 10 bytes unused 

name, 20 $$ user's name 
date, 6 $$ date of last use 
time, 4 $$ time of last use 
10 . hours ,1 

minutes , 1 
seconds ,1 
hund , 1 

score, 2 $$ most recent test score 
15 status ,256 , block $$ next block begins here 

Once a variable block is defined, all subsequent variable definitions are part of the defined 
block, up to the next variable block definition. If definitions within a variable block use up more 
space than is reserved for the block, a compile error occurs. 

When the length of the variable block is not known, the size argument can be left blank. In 
20 this case, the variable block is given whatever size is required to hold all variables subsequently 
defined, up until the next block definition. 
Sharing Definitions Among Source Files 

If a program is spread over several source files, care must be taken to make the global 
variable definitions agree for each file. This is normally done by placing all the global definitions 
25 in one file and including a copy of the definitions in the other files with use commands: 
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tax Lglobals (defines block) 

lastname , 15 
f irstnam, 10 
mi , 1 
5 stunuin,9 
P(64) ,1 
score , 4 

tax la,globaIs (defines block) 

10 use taxl,globals 

tax lb,globaIs (defines block) 

use taxl,globals 

In this example, all of the variables for the files taxi, taxla and taxlb are defined in taxL 
1 5 The use commands in taxla and taxlb just include a copy of the definitions already made in 
taxi. 

Sharing Some Definitions But Not Others 

Sometimes, it is desirable to define some variables which are used by an entire set of 
source files, and other variables which are unique to each individual source file. Since there is 
20 only one memory area for all global variables, the definitions of the variables for individual source 
files must naturally be coordinated to avoid conflicting definitions. This can be accomplished 
using a combination of variable blocks and redefinition. 

The following example applies this technique to the files taxi, taxla and taxlb by adding 
'variables defined in taxla and taxlb: 
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taxl,giobaIs (defines block) 

iastname , 15 
firstnain, 10 
mi , 1 
5 s tunum , 9 
P(64) ,1 
score t 4 
★ 

taxla,2048 , block 
10 taxlb, 2048, block 

tnxla,globals (defines block) 

use taxl,globals 

1 5 @ taxla , ownvars ,2048 , block 

xloc , 2 
yloc,2 
interest , 8 , r 

20 

taxlb,globals (defines block) 

use taxl,giobais 
* 

Q taxlb , ownvars , 20 48, block 
25 linella,8,r 
•linellb,8,r 
linel2,8,r 
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In this example, the definitions used by all three files include the 2048-byte variable^locks 
"taxla" and "tax lb". These variable blocks are data areas reserved for the source files of the same 
name. The source files taxla and taxlb then redefine their own block using the name "ownvars" 
and define their own variables within this block. Making "ownvars" a block variable ensures that 
the variable definitions in taxla and taxlb do not extend beyond the areas reserved for them. 

Unlike other redefined variables, redefined block variables permanently affect variable 
allocation. If taxla defines another block after "ownvars", this block will conflict with the 
variables defined in taxlb. 
Accessing Other Memory Segments 

Sometimes it is desirable to access data stored in areas of memory other than local and 
global variable space. This can be accomplished using the transfr and exchang commands, 
transfr 

The transfr command transfers data from one place to another. It has the general form: 
transfr from-base-address,ofFset;to-base-address,offset;length 

Boxhfrom-base and to-base must be from among the following keywords; 

• routvars, r 

Router variables. This is a special unstructured 256-byte buffer which can be accessed 
only via transfr and exechang. The router buffer provides an area for data that is not 
normally used by lessons. One common use for this buffer is for keeping user 
performance data for an activity manager. 

• display, d 

CGA screen display memory. Note that display memory for other display types EGA, 
VGA, etc.) cannot be accessed whh transfr, 

• global,g 
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Global variables. ^ 

• local,! 

Local variables. 

• sysvars, s 

5 System data area. CAUTION: do not use this area for data storage. 

• sysprog,p 

System program area. CAUTION: do not use this area for data storage. 

• absolute, a 

Absolute memory location. 
10 The following example transfers the router variables into local variables and then displays 

the student's sign-on name. 

define local 
localr ,256 

info , 8 

15 . name, 20 

define end 



transfr routvars,0; local, varloc (localr) ;256 
20 at 10:5 

write The student name is «a,name» 

exchang 

The exchang command is similar to the transfr command, but swaps two areas of 
. memory. 

25 The following code uses the exchang conmiand to swap a pair of 2-byte variables: 
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if xi < xO 

exchang g,varloc(xO) ;g , varloc (xl) ;2 

endif 

This is equivalent to but simpler than the following: 
5 if xl < xO 

calc tenp c= xO 

xO c= xl 
xl c= temp 

endif 

1 0 Accessing Absolute Memory 

The transfr and exchang commands can also be used to access any absolute memory 
address in the computer. This is accomplished using the base-address keyword absolute. The 
offset is then a four-byte integer location. 

A useful function when transferring to or from absolute memory locations is absIocQ, 
1 5 which returns the absolute location in memory of a variable. This is often used to pass the 
location of data to a library routine, as follows: 

pack naine ;namelen;Wendell Oliver Holmes 

library rticlib , answer (absloc (name) ,namelen) 

The advantage to using abslocQ here is that unit mclib,answer does not need to know 
20 whether the data is in the local or global segment-it can copy the data directly from the absolute 
memory location. 

Technical Notes on Absolute Addresses 

The abslocQ function returns four-byte values over a continuous integer range. To 
* convert an abslocQ value to the segment:offset form required for passing data to DOS functions, 
25 the following calculations can be used: 
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define local 
terrp / 4 

segment , 2 
offset ,2 
5 define end 



calc temp <= absloc (myvar) 

segment <= temp $ars$ 4 
10 offset c= temp $mask$ hOOf $$ extra 0 required 

This calculation yields the highest possible segment address and the lowest possible offset 
address. 

The calculation to go from an existing segment: offset address to an absolute integer 
address is: 

15 calc segment <= sysloc (global) $$ or local, as appropriate 

offset c= varloc (variable) 

texnp c= ((segment $mask$ hOOOOffff) $cls4$ 4) + 

{offset$mask$hOOOOffff ) 

Accessing the Memory Pool 
20 Data can also be transferred from variables to the TenCORE memory pool, as in: 

memory write ,mempool ,moff set ,bigbuf ,buf size 

Where write is a keyword specifying the direction of the transfer; "mempool'^is the name 
of the memory pool block; "moffset" is the offset into the memory pool block; *'bigbuf is the 
variable at which to start the transfer; and "bufsize" is the number of bytes to transfer. 
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The keyword write specifies that the transfer is from variable space to the memory pool; 
read transfers from the memory pool to variable space; and exchange sv^aps the contents of the 
two. 

For more information on this topic or on primary and secondary memory pools, refer to 
5 the memory command. 

Command List 

171 

187 

10 at/aff 

beep ZZ"Z^'Z 192 

block ,54 

^^''••V 'ZZZl95 

branch 

^^Ic - ----''"^ 

^^'^^ 198 

calcs 200 

^''^^^ 201 

clearu 202 

20 clock 203 

color 204 

colore 205 

compare 207 

compute 209 

25 date 2io 

debug ''^^'^Z^Z'^^ 

device 212 

disable 

Z'ZZ'"i\6 

20 dot 219 

draw 220 

ellipse 221 

else ; 222. 

elseif. 223 

35 enable 223 

endif. : *; 227 

endloop 227 

erase ; 228 

error 229 

40 exchang 230 

exec !"^I*!^^ZZ*!ZI!'232 



SUBSTITUTE SHEET (RULE 26) 
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exitsys rr:..236 

extin 237 

extout 239 

fill 240 

5 find 241 

flow 244 

font 261 

goto 272 

if 273 

10 image 275 

initial 284 

intcall 287 

loadu 296 

loop 297 

15 memory 299 

mode 306 

move 311 

nextkey 312 

nocheck 315 

20 operate 315 

origin 316 

outloop 318 

pack, packz packc, packzc 319 

page 323 

25 palette 325 

pause 329 

perm 336 

polygon 341 

press 342 

30 print 344 

put 346 

receive 348 

reloop 350 

return 351 

35 rotate 353 

scale 355 

screen 357 

seed 363 

set 364 

40 setbit 365 

setc 366 

show 368 

showa 370 

showh ^ 371 

45 showt 372 

showv 374 

status 375 

text 380 
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width ^396 

window 39g 

write 402 

writec 4Q4 

5 zero 406 



area 

Manages pointer input areas. 



10 area keyword;... 



define 


defines a pointer area 


nignhght 


specifies highlight type and color 


disable 


temporarily deactivates current pointer areas 


enable 


reactivates disabled pointer areas 


clear 


deletes current pointer areas 


select 


highlights a pointer area 


save 


saves current pointer areas to a named memory block 


restore 


retrieves pointer areas from a named memory block 


delete 


deletes named pointer area memory blocks 


reset 


deletes all named pointer area memory blocks 


toggle 


highlights or dehighlights a toggle pointer area 


inarea 


determines if a location is within a pointer area 


dir 


returns list of active pointer area identifiers 


key 


returns the area identifier of a specified key 
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info reports the attributes associated with a pointer area ^ 

repos repositions all pointer areas in a window 

Description 

Facilitates pointer input within defined areas of the screen. Once a pointer area has been 
5 defined, a Click or other pointer action within the area generates a specific input value, just as if a 
keyboard key had been pressed. Appropriate coding can cause such an input to trigger a flow 
branch to another unit, break a pause, generate typing at an arrow or any other action desired. 

Up to fifty active pointer areas may exist; this number can be increased with the /sa= 
command line option. The number of currently defined pointer areas is stored in the system 
10 variable zareacnt. zmaxarea holds the maximum number of areas allowed. 

area definitions are cleared upon a jump branch to a new main unit. As part of the 
initializations for a new main unit, the default set of areas are activated, area definitions are 
saved when a window is opened and restored to their previous state when the window is closed 
unless noarea is used on the window close. 
15 Pointer areas can be highlighted and dehighlighted automatically as the pointer moves in 

and out of the areas. The current pointer areas, together with their characteristics, can be saved in 
a named memory block; these can be deactivated and reactivated using the name. Pointer areas 
can be temporarily disabled and enabled. 

area define; [LOCATION]; [LOCATION]; [action=KEY, action=KEY...] 
20 Defines a rectangular screen area, whose opposite corners are identified by the two 

locations, within which any of the pointer actions listed generates an input key. Pointer areas with 
'several defined actions and key values may be continued on following lines. 

The following pointer actions can generate input values. Each pointer action has its own 
keyword: 



10 
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click= any pointer button is pressed ^ 

left=, right= the left or right pointer button is pressed 

clickup= any pointer button is released 

Ieftup=, rightup=the left or right pointer button is released 

add=, sub= a second button is pressed or released 

enter=, exit= the pointer enters or leaves an area 

If the keyword left or right is used, then click cannot be used. If leftup or rightup is 
used, then clickup cannot be used. If click= is the only action specified, the click= keyword can 
be omitted. 



KEY may be any ordinary key value, such as a,b,c, %n, etc. or one of the pseudo-keys 
°/oinputl - 999. 
Example i 

Inputs the value %enter when a button is clicked within the area defined by 10:20; 1 1:30. 
In this case the keyword click= is optional (click=%enter). Coupled with the following now 
15 conmand, the area input causes a jump to unit nextunit, 

area define; 10:20; 11:30; %enter 

flow jump; %enter; nextunit 

Example 2 

Inputs the value %"L" if the left button is pressed, and %"R" if the right button is pressed. 

20 area define; 100,200; 300,250; lef t=L, right=R 

Example 3 

Inputs the pseudo-key %input999 when the pointer enters the area defined by 5:3; 6:10. If 
the left button is released in the area, %fl0 is generated. 

area define; 5:3; 6:10; lef tup=%f 10 , enter=%input999 
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Example 4 ^ 

Defines the entire screen as a pointer area. Clicking the right button will input the pseudo- 
key %other. 

area define; ; ; right=%other 

Example 5 

Defines a rectangular area from 10:10, 30 characters across for 2 lines. A pointer button 

click will input the %fl key, 
at 10:10 

area define; 30,2; ; click=ftfl 

Example 6 

Defines a rectangular area around the text "Topic 1 : Introduction" allowing for fixed or 
variable spacing. A click while in the area will input %"!*'. 
at 15:10 

write Topic 1: Introduction 

area define; 15:10; zx , zy+zf onth ; click=%"l" 

Example 7 

Is continued over two lines. 

area define; 200,150; 400,170; lef t=a , right=%home , lef tup=b , rightup= 

«h01» ,enter-%inputl ,exit=%input255 

area define; [LOCATION]; (LOCATION]; (action=KEY, action=ICEY...] [;modifier; 
modifier .,.] 
iModifiers 

The following modifiers can be used optionally with an area define statement. Any 
^number of modifiers may be used and they can be listed in any order, setid and getid are mutually 
exclusive. 
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default preserves the active pointer areas for all subsequent main units. (Normallyra 

branch to a new main unit that erases the screen clears all pointer areas.) See also 
Default Area Highlighting. 

priority assigns a priority from 0 to 1 5 in order to establish a precedence for overlapping 
areas. Level 15 is the highest priority. 

If a priority is not set, the area is assigned a level of 0. If pointer activity occurs 
within two or more overlapping pointer areas, the highest priority area will take 
precedence. If overlapping pointer areas have the same level, the last defined area 
takes precedence. 

getid specifies a variable to hold the unique 2-byte pointer area identifier that is 

automatically generated by the system when a pointer area is defined. System 
generated identifiers are always negative, between -32,768 and -1. The ED is used 
to identify a specific area in forms of the area command and is returned in system 
variable zinputa. 

setid specifies a number which becomes the pointer area's unique identifier. Author- 
specified identifiers, must be between 1 and 32,767 to avoid a possible conflict 
with system-generated identifiers. The definition of a pointer area whose identifier 
is identical to that of an existing pointer area will result in the existing pointer area 
being redefined. The ID is used to identify a specific area in forms of the area 
command and is returned in the system variable zinputa. 

Example I 

The pointer area definition will be a default area upon entering a new main unit. The area 
can be referenced later using the ID received in the variable arealD. 

area define; 5:10; 10:25; lef t=b , right=B ; default; getid.arealD 
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Example 2 — 

Inputs the pseudo-key %inputl when either button is pressed while in the rectangular 
area. The area can be referenced by the specified ID value 1 . 

area define; 100,100; 200,110; %inputl; setid,l 

5 Example 3 

Inputs the hexadecimal value 7000 when the pointer enters the rectangular area. If any 
other pointer area with a lower priority level overlaps this area, then this one takes precedence 
because it has the maximum priority level. 

area define; 400,150; 450,200; enter= «h7000» ; priority, 15 

10 area highlight: COLOR 1 off [; xor] (track | toggle] 

Controls the highlighting color of all subsequent pointer areas. Area highlighting is off by 
default. A single area highlight statement affects all subsequent area define statements, but not 
pointer areas defined previously. Highlighting is reset to off by an initial statement. 

The system variable zareahl holds the area id of the currently highlighted area (or 0 if no 
15 area is highlighted). 

Highlighting to the given color is produced by plotting a box in an exclusive-or (XOR) 
mode and color over the screen area The upper-left pixel of the screen area is used in determining 
the box color that will XOR the screen to the desired highlight color. 
Modifiers 

20 The following modifiers can be used optionally with an area highlight statement but only 

when a color is specified, track and toggle are mutually exclusive. 

xor specifies that pointer areas are to be highlighted by directly XORing the screen 
with the color specified 
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track 



dehighlights the area only when the pointer enters another area that has 



highlighting enabled 



toggle 



disables automatic area highlighting and allows author-controlled highlighting (S 



ee 



area toggle.) 



Default Area Highlighting 

When default areas are in effect and a main unit is entered via a jump - type branch, area 
highlighting does not occur until after one of the following events: 

• a branching command is executed (loop, jump, jumpop, branch, doto, goto) 

• input is requested from the system (pause, arrow, nextkey, delay) 

• the end-of-unit is reached 

• cenain commands that may have a long execution time are executed (image, fill) 

• An enable command with the keyword area, pointer or break 

These are the same points at which the pointer position is checked to see whether it has 
just entered or exited a highlighted area. 

This delay allows the author time to get the display on the screen for which highlighting is 
desired. If a branch is required or if input must be requested before building the screen, the author 
must first issue a disable area statement to disable highlighting. After building the screen, enable 
area turns on any highlight. 



Produces red+ highlight areas. It uses the upper left corner of the area as an XOR 
reference color. Thus, the color of the pixel at 250,320 (the upper left corner of the area) is used 
to determine what color to XOR the area with to produce red+. 



Example 1 



area 



highlight ; red+ 



area 



define; 250,300; 400,320; click=%flO 
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Example 2 ^ 

Turns off highlighting for all subsequently defined pointer areas, 
area highlight; off 

Example 3 

XORs subsequently defined pointer areas with blue. The areas will be highlighted when 
the pointer enters an area but will not be dehighlighted until it enters another area. 

area highlight; blue; xor; track 

Example 4 

Disables automatic area highlighting, area toggle can be used to highlight these areas. 

area highlight; white; toggle 

area disable [; arealD/sl [; noplot] 

Temporarily disables the pointer areas having the identifiers specified. The disable 
ke\avord alone temporarily disables all defined areas, A disabled pointer area no longer produces 
pointer input or a highlight. If a pointer area is highlighted when disabled, highlighting is turned 
off unless the noplot modifier is present. 
Example 1 

Disables the pointer area whose identifier is contained in the variable idvar. If the pointer 
area is currently highlighted, it will remain highlighted. 

area disable; idvar; noplot 

Example 2 

Disables the pointer areas whose identifiers are 1 and 2. 

area disable; 1,2 

Examples 

Temporarily disables all pointer areas, 

area encQsle 
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area enable [; arealD/s) 

Enables pointer areas previously disabled with area disable. 
Example 1 

Enables the pointer areas whose identifiers are contained in the array elements areaED(l), 
5 arealD(2), and areaID(3). 

area enable; arealD (1) , arealD (2 ) , arealD (3) 

Example 2 

Enables all pointer areas 

area enable 

10 area dear [; [arealD/s][; noplot] [; default]] 

When used with area identifiers, clear removes the specified pointer. When used without 
area identifiers, clear removes all areas, .\reas are cleared regardless of being disabled. 

If a pointer area is highlighted when it is cleared, the highlighting will be turned off unless 
noplot is used, 

15 The default modifier is used to remove any area definitions that have been set with the 

default modifier. 
Example 1 

Deletes the pointer areas whose identifiers are contained in variables ID I and ID2 

area clear; IDl, ID2 

20 Example 2 

Deletes all pointer areas. A following jump branch will restore any unit default pointer 

areas. 

- area clear 
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Example 3 ^ 

Deletes all pointer areas from the entire screen, leaving any highlight on. When the 
window is closed, any previous areas are restored. 

window open; 100,100; 300,300 
5 area clear; ;noplot 

window close 

area select; arealD | pointer \ off 

Highlights the area specified by the identifier or currently under the pointer. If off is 
10 specified, any highlighted area is turned off. select does not work with toggle highlight areas. 

Only one area is highlighted at a time; any previously highlighted area is turned off. 
Example 1 

Highlights the area whose identifier is contained in the variable alD. 

area select ; alD 

15 Example! 

Turns off any highlighted area. 

area select; off 

Example 3 

Before opening the window, all areas are disabled. This turns off any highlight that is on. 
20 After closing the window, the areas are re-enabled and any area under the pointer is highlighted. 

area disable $$ turn off areas and highlight 

window open, 100 100 ; 300 , 300 

close 

enable $$ turn areas on again 

select ;pointer $$ highlight if pointer on area 



window 
25 area 
area 
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area save; 'NAiME* | local ^ 
area save; default 

Saves the current set of area definitions in a memory pool block or the default buffer. The 
name can be either a text literal or contained in a variable. Named blocks can be restored later in 
5 any unit. 

The local keyword saves the area settings in a memory pool block specific to the current 
unit. A local block can be restored only in the unit which saved it; it is deleted automatically when 
execution of the unit ends. 

Saving the current area settings to the default buffer makes them the default area settings 
10 for all new main units. They are automatically reset on a jump to another unit. 

The memory pool is used by the commands; memory, image, window, status, area, 
flow, font and perm. Memory blocks are tagged as belonging to a specific command type at 
creation and cannot be accessed by other commands using the memory pool; different commands 
can use the same name for a memory block without conflict. 
15 Example 1 

Saves the current pointer areas in the named memory block leveU 

area save; 'levell* 

Example 2 

Saves the current pointer areas using the name contained in the variable areavar 

20 area save ; areavar 

Example 3 

Saves and restores the active flow settings over a subroutine call in a memory pool block 
unique to the executing unit. The block is automatically deleted when the unit is exited. 

area save ; local 
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do routines , graph *«- 

area restore; local 

Example 4 

Makes the current area settings the defaults for all subsequent units that are entered by a 
5 jump branch. 

area save ; default 

area restore: 'NAME' | local [; delete ) [; noplot 1 
area restore; default [; noplot \ 

Replaces the current area settings with a previously saved set. Optionally, the named or 
10 local block can be deleted from the memory pool by using the delete modifier 

Any areas highlighted when saved are highlighted when restored unless the noplot 
modifier is used. 
Example 1 

Saves and restores the current area settings over a library call. The library routine can 
15 alter the active area settings as desired without affecting the calling program upon return. 

.Alternately, the area save and restore could be built into the library routine to provide a more 
easily used tool. 

area save; 'areas' 

library routines, graph 
20 area restore; 'areas' 

Example 2 

Saves and restores the active flow settings over a subroutine call in a memory pool block 
unique to the executing unit. The block is automatically deleted when the unit is exited. The 
highlight status is not restored. 

25 area save; local 
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do routines , graph 

area restore; local; noplot 

Example 3 

Restores the unit default set of pointer areas. 

5 area restore; default 

area delete; 'NAME'l local 

Deletes a saved set of pointer areas from the memory pool without affecting any current 
pointer area definitions. 
Example 

10 Deletes from memory the areas saved under the name menu. 

area delete; *menu' 

area reset 

Deletes all named sets of pointer areas from the memory pool without affecting current 
definitions. The default set of area settings are unaffected. 
15 area toggle; arealD 

Highlights or dehighlights the pointer area whose identifier is specified. This keyword 
option only operates on toggle pointer areas (as set by area highlight) It is intended for authors 
who want total control over the highlighting of pointer areas. Unlike area select, more than one 
pointer area can be highlighted. 
20 Example 

Highlights the pointer area whose identifier is contained in the variable cID. 

area toggle ; cXD 
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area inarea: LOCATION; arealD ^ 

Determines whether the specified location is within a pointer area. If so, the area's 
identifier is put into the variable arealD, If the location is within multiple areas, the highest 
priority area or, if levels are the same, the last defined area takes precedence. 
5 If the location is not within any area, the variable is set to 0. 

Example 

Sets whichlDio 1, the identifier belonging to the priority 15 pointer area. 

area define; 90,100; 120,160; click=%space ; 

priority, 15; setid,l 

10 area define; 90,100; 120,160; click=%home ; 

priority, 6; setid, 2 

area inarea; 100,155; whichlD 

area dir; idBuffer [;length| 

15 Returns the identifiers of all active pointer areas. To report on the maximum number of 

pointer areas, the area identifier buffer should be zmaxarea*2 bytes in length. 
Example 

Returns the area identifiers of all currently active pointer areas in the array buffer id 

define local 

20 id(50) ,2 $$ use system default for array length 

define end 

area dir; id(l) ; 2*zareacnt 

area key; KEY; arealD 
25 Returns the identifier of the pointer area which includes the specified key in its pointer 

action list. If two areas have the specified key listed, then the identifier of the highest priority area 
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is returned. If the areas have equal priority, then the identifier of the last defined pointer areS is 
returned. 

area info; arealD; infoBufFer48 

Returns the attributes of an enabled pointer area into the buffer specified. The pointer ai 
5 is selected by providing its identifier. The structure of the 48-byte buffer is as follows: 



Attribute 


Bvtes 


lower left x coordinate 


2 


lower len v coorainate 


2 


upper right x coordinate 


2 


upper right v coordinate 


2 


highlight color of area 


4 


type(0=none; l^hishliaht: 2=track) 




priority (O=none; 1.. 15=prioritv level) 




default (O=none; l=default) 




window open level (zwindows) 




reserved 


16 


left= kev value 


2 


ri2:ht= kev value 


2 


enter= kev value 


2 


exit= kev value 


2 


lcftup= key value 


2 


rightup= kev value 


2 


add= kev value 


2 


sub= kev value 


2 



Example 

Reads the information from the area whose identifier is contained in the variable ID2, into 
the buffer named areadata. 

area info; ID2 ; areadata 

If a window is in effect when this statement is executed, the specified coordinates will be 
relative to the current window, 
area repos; xOffset,yOffset 

Adjusts all pointer areas by the absolute screen dimensions specified. If one or more 
windows are open, it operates only on areas created while the current window was open. 
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Example ^ 
Moves all pointer areas to the left 20 pixels and up 100 pixels. 

area repos; -20,100 

System Variables 
zreturn 

The save, restore, reset and delete forms of the area command, which use the memory 
pool, report on success or failure in zreturn. In addition, the select and toggle forms also report 
error conditions through zreturn. All other forms set zreturn to ok (-1). The major zreturn 



values are: 

-2 Redundant operation; area is already selected 

-I Operation successful 

10 Name not found 

1 1 Select or toggle of invalid highlight type 
18 Unable to fill memory pool request 
Miscellaneous 

zareacnt Number of currently defined pointer areas 

zareahl area id of currently highlighted area (else 0) 

zinputa area id of area causing the current zinput value (else 0), set when zinput 
updated 

zmaxarea Maximum number of areas that can be defined 
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asmcall ^ 

Calls an assembly language routine loaded into variables. 

asmcall buffer [ .variable] 

buffer starting variable where routine is loaded 
5 variable puts offset of specified variable into register BX 

Description 

Calls an assembly language routine which has been loaded into local or global variables. 
Segment register DS points to the start of variables, if the optional variable is used, register BX 
is set to the offset of variable. The result is that DS:[BX] points to the variable listed as the 
1 0 second tag. A far return must be executed at the end of the routine to return control to 

TenCORE. The value of the AL register is returned in the TenCORE system variable zreturn. 

The assembly language routine may alter any of the microprocessor registers, but SS and 
SP, if changed, must be restored to original values before returning to TenCORE. 
Addresses 

1 5 The following system-defined function references are sometimes useful with asmcall: 

sysloc(global) Segment address of global variables 
sysloc(local) Segment address of the current unit's local variables 
varloc(variable) Offset address of variable 

absloc(variable) Absolute location of variable within memory, expressed as a 4-byte offset 
2^ with no segment. This corresponds to the segment: offset address as 

follows: 
segment = abslocQ SarsS 4 
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offset = abslocO SmaskS hOf ^ 
If you have the segment and offset and wish to convert to the absolute location, use 
following calculation: 

absloc = ((segment SmaskS hOOOOflfff) $cls4S 4) + (offset SmaskS hOOOOffff) 
5 Example 

Reverses the bits in a byte. 

* 

define global 

asmbuff(12),l $$ buffer for assembly language program 

10 asmdata ,1 $$ integer byte to reverse 

define end 

* Load short assembly language routine by direct execution. 
•* 

15 * The routine begins with DS:BX pointing to the TenCORE 

* variable "asmdata". The program loads and reverses 

* the byte, leaving it in register AL. After the asmcall , 

* zreturn is set to the value left in AL. 
* 

20 * The set command used here allows the programmer to 

* emulate the structure that would be used for assembler 

* programming. 
★ 

set asrobuff<l) $$ mirror proc far 

25 h8a, h27 $$ mov ah, [bxl ; fetch byte 

h0b9, h08, hOO $$ mov cx,0008 ; shift 8 bits 
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* ' $$ mirrori: 

hOdO, hOec $$ sh rah,01 ; move LSB to CF 

hOdO, hdO $$ rcl al,01 ; shift CF into AL 



5 * 



h0e2, hOfa $$ loop mirrori 

hOcb $$ retf ; fa^, return 

$$ endp 



calc asindata c= h55 $$ trial value to demons tate bit reversal 



asmcall asmbuffd), asmdata $$ call routine, pointing to data 
at 4:4 

write Original value = «h,asmdata» hex 
Reversed value = «h,2return» hex 

15 System Variable 

zreturn Holds the value of AL register upon return 

at/atf 

Sets the screen location and text margins, 
^t [LOCATION] [; LOCATION] ' 

20 Description 

Sets the current screen x-y location and the left text margin to the first LOCA TION in the 
tag. The system variables zx, zy and zmargin are updated to this new location. If character 
. coordinates are used to specify the at location, the zx-and zy system variables contain the lower 
left graphic coordinates of the character cell. 
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A right text margin (which is initially set to the right screen or window border) can-be set 
by specifying a second LOCATION, The right n^argin is found in the system variable zrmargin. 
Text that hits the right margin is automatically wrapped to the left margin. See text margin for 
the available text wrapping options. The right margin is ignored by the obsolete charset character 
5 plotting.) 

The blank-tag form sets the left margin to the current screen location. This form is 
equivalent to the following statement: 
at zx,2y 

The atf form of the command allows for the automatic adjustment of the zy position 
10 based on the height of the first following real plotting character. The top pixel of this first 

following real character is placed at the same y-position as the top of a standard font character. 
This action of atf provides for an apparent fixed top margin for text even if the text contains 
unknown starting embedded text attributes such as size and font. The adjustment to zy occurs in 
the following write or show statement when the first real character is plotted on the screen. 
15 Examples 
Example 1 

Writes text starting at x = 10, y = 150. 

at 10,150 

write This is line one of my text. 
20 This is line two at the same left margin. 

Example 2 

Writes text starting at line 7, character 3. 

at 7:3 

write The line: character format is used for text more often than the 
25 graphic x,y format. 
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Example 3 ^ 
The text margin statement with wordwrap sets plotting to perform automatic wrapping 
of words at the right text margin stated in the following two location at. The second location on 
the at sets up a right margin at the 30th character position on the screen (or current window). 
5 The line number part of the second location is not used by the system plotter. 

text margin; wordwrap 

at 5:10; 20:30 

write This text will appear on the screen as a paragraph only 20 
characters wide regardless of how long the lines look in source code... 

10 Example 4 

By using atf commands, the top of the text from the two write statements appear to have 
a common top margin on the screen. The second write statement that has an initial embedded 
size 2 code sequence adjusts the system variable zy upon plotting the "S" so that the top of the 
"S" appears in the same location as the standard size font. 

15 atf 10:10 

write Size 1 text 
atf 10:30 

write Size 2 text 

* $$ Embedded size 2 at start of text 

20 System Variables 

The following system variables reflect the actions of the at statement: 

zx X-coordinate of screen location 

zy Y-coordinate of screen location 

zline Line number 

25 zspace Character number 
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zxycolor Color of the pixel at screen location 

zmargin Left text margin 

zrmargin Right text margin 



beep 

5 Causes the speaker to generate a controlled beep. 

beep duration [, hertz ] 

duration the length of beep, in seconds 
hertz frequency in cycles per second 

Description 

10 Produces a tone of the frequency and length specified in the tag. If the frequency is not 

specified, it defaults to 1000 Hz. 
Examples 
Example 1 

Produces a small, perhaps recognizable musical tune. 



beep 


.15, 261.3 


S$C 


beep 


.2, 349.66 


SSF 


beep 


.2, 440.88 


$$ A 


beep 


.4, 523.25 


S$C 


beep 


.2, 440.88 


$$ A 


beep 


.4, 523.25 


$$C 


Example 2 







Demonstrates user control of a beep command. 



3NSDOCID <WO ^ 9907007 A2_ I _> 



wo 99/07007 PCT/US98/15627 

193 

define local 

length ,4,r $$ length of beep 

define end 

★ 

5 at 5:5 

write How many seconds do you want the speaker to beep? 
arrow 6 : 5 
store length 
at 8:7 

10 . write Please enter a number, like 2,3 or 5 
ok 

beep length 

endarrow 

Frequencies 

15 A one-octave scale from middle-C has the following frequencies. Multiply or divide by 

two for other octaves: 

C 26L63 

C# 277.18 

D 293.66 

20 D# 311.13 

E 329.63 

F 349.23 

F# 369.99 

G 392.00 

25 / G# 415.30 

A 440.00 
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A# 466.16 
B 493.88 
C 523.25 

To calculate more precise frequencies, use a multiple of 1 10 as a standard "A" and 
5 multiply by the twelfth root of 2 for each half-tone increment. 

block 

block [LOCATION 1 ;[LOCATION ] ;[LOCATION ] [;[frompage][,to page]] 
Description 

Copies a rectangular screen area from one location to another including across display 
10 pages. Operational only on 16- and 256-color screens. The block command works solely with 
absolute plotting coordinates; it is not affected by origin, rotate, or scale. 

The first two locations specify the corners of the source area to be copied; if not specified 
they default to the entire screen. The third location is the upper-left corner of the destination; it 
defaults to the same position as the source area. 
15 The fourth argument (frompage) is the source page number; it defauhs to the current read 

page (zrpage). 

The last argument (topage) is the destination page number; it defaults to the current write 
page (zwpage) 

block xl,yl; x2,y2; x3,y3 $$ copy one area of screen to another 
20 block xl,yl; x2,y2;; 2,1 $$ copy from page 2 to page 1 

block xl,yl; x2,y2;; 2 $$ copy from .page 2 to current page 

at 10:10 

block 6,5;;5:10 $$ copy 6 chars, 5 lines from 10:10 to 5:10 
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box 

Draws a solid box or a frame on the screen. 



box [ LOCA TION ] [; [ LOCA TION ] [; Xframe [, Yframe]]] 
Description 

5 Draws a solid box or frame on the screen in the foreground color. See the Command 

Syntax Conventions for a description of LOCATION, The erase command is identical to box 
except that it uses the background color for drawing. 

The presence of a frame width argument signifies that a frame rather than solid box be 
drawn. The widths of the right and left sides are specified in pixels by the first frame argument 
10 while the second frame argument specifies the top and bottom widths. If the second frame 

argument is absent, the top and bottom frame width is set to best match the side width in aspect 
appearance on the screen. 
Examples 
Example 1 

15 The entire screen (or window) is made blue with a white frame 5 pixels wide. 

color blue 
box 

color white+ 

box ; ; 5 

20 Example 2 

A solid rectangle 200 pixels wide by 100 pixels high is put on the screen in the foreground 
color. Graphic coordinates are used to specify each x,y coordinate for a location. 

box 101,101; 300,200 



BNSDOCID: <W0 9907007A5 ! > 



wo 99/07007 



PCT/US98/15627 



196 



10 



Example 3 

The text in the write statement is given a red frame 2 pixels wide. The text measure 
command is used to determine the screen area that a following paragraph of text plots over on 
the screen. This information is returned in the system variables zplotxl, zplotyl for lower left 
comer and zplotxh, zplotyh for upper right corner. 

text measure S$ initialize text measuring 

at 100,150 

write This is a paragraph of text of arbitrary 
length that will be nicely framed. . . 



color red+ 

box 2plotxl-2,zplotyl-2;2plotxh+2, zplotyh+2; 2 

$$ frame the text 
15 Example 4 

A blue box 20 characters wide and 10 lines deep is put on the screen starting on the 10th 
line. Since the box command does not change the system variables zx and zy as set by the at 
command, the text will also occur at the start of line 10. 

at 10:1 

20 color blue 

box 20,10 

color white+ 

write This text appears in the box... 
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branch 

Transfers execution to a labeled point in the same unit, 
branch label | q 

branch SELECTOR: label j q; label | q;... 
5 label Any valid label present in the current unit. A label is a numeral 

optionally followed by 1 to 7 letters or numerals, in the command 
field of a line, 
q Branch to the end of the current unit. 

Description 

1 0 Alters the flow of execution within a unit, by transferring execution to the line following 

the specified label, or to the end of the unit if the keyword q is specified. A blank entry in the 
selective list is used to fall through to the following command. 
Example 

If name is already set, the branch command will skip the arrow structure. 

15 branch name=0 ;; Iskip 

at 10:10 

write Enter your name. 

long 8 

arrow 11:10 

20 storea name 

ok 

endarrow 



Iskip 
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at 15:10 

v;rite Welcome , «showa , naitie» . 

caic 

Assigns a value or calculation to a variable. 
5 calc variable expression 
Description 

The expression to the right of the assignment arrow can be any combination of constants, 
literals, variables, operators and functions so long as it evaluates to a single numeric value, 
calc cannot work with variables greater than 8 bytes in size. 
10 The command name does not need to be repeated for additional lines of calculations. 

For more information on calculations, assignments, and variables, refer to the section 
Variables, Calculations, and Data Transfer in this document. 
Example 

Increment a counter, compute a percentage, and evaluate a complex expression. 

15 calc count c= count + 1 

score <= correct / total 
dist <:= (1/2) * g * (t**2) 

calcc 

Selectively performs an entire calculation and assignment 
20 - calcc SELECTOR; varl expl; var2 <=:exp2;;... 
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Description ^ 
calcc is a selective form of calc that performs one of a list of calculations, based on the 
value of the selector. Each calculation in the list can assign a different value to a different 
variable, if no calculation is to be performed for a particular value of the selector, a null tag (;;)is 
5 used. 

The calcc statement can be continued in the tag field of subsequent lines. 
Examples 
Example 1 

review is set if the selector right is 1 ; score is assigned \f right is 2 or greater. Nothing 
1 0 occurs for a zero or negative value of right. 

calcc right;;; review <= -1; score c= {right/5) *XOO 

Example 2 

The value 4 is assigned to section if the selector complete is true; if false, no assignment 

occurs. 

15 calcc complete; section c= 4;; 

Example 3 

cobmn is assigned \i select is 1, apples is assigned \i select is 2, and total is assigned 50 if 
select is 3. Nothing occurs if select is negative, zero or greater than 3. 

calcc select, , , 
20 column c= 22 + pointer; 

apples <= bushels* 47 
total <:= 50;; 
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calcs 

Selectively assigns a value to a variable. 

calcs SELECTOR; variable exp 1 ; exp2;;... 
Description 

5 calcs is a selective form of calc that evaluates one of a list of expressions and assigns it to 

a given variable. Based on the value of the selector, an expression is selected and evaluated from 
the list on the right of the assignment arrow and assigned to the specified variable. If no 
assignment is to be performed for a particular value of the selector, a null tag (;;) is used; the 
variable remains unchanged. 
10 The calcs statement can be continued in the tag field of subsequent lines. 

Examples 
Example I 

The selector month is used to set the variable days to its proper value. The selective 
assignment is continued over two lines. 

15 calcs month; days c=; ;31 ;28 ;31 ;30;3i ;30; 
31;31;30;31;30;31 

Example 2 

If complete is true, section is assigned the value 4; otherwise it is set to the evaluation of 
the expression /a5/*2 

20 calcs coiT^lete; section c= 4;last*2 
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circle 

Draws a circle, 
circle radius [ ,fill | angle , angle! ] 
Description 

5 Draws a circle of the specified radius with its center at the current screen location in the 

current foreground color. 

The optional fill keyword produces a solid circle filled with the current foreground color. 
The current screen location is not altered after a one-tag circle, so concentric circles can 
be drawn without resetting the screen location. 
10 The three-tag form draws an arc. Arcs are always drawn counter-clockwise from angle I 

to angle2. As a resuh, different arcs are drawn depending on which angle is specified first. For 
example, circle 100,0,90 draws a quaner of a circle, from 0 to 90 degrees. The statement circle 
100,90,0 draws three-quarters of a circle, from 90 degrees around to 360 (or 0) degrees. 
For an arc, the current screen location is updated to the ending (last) arc position. 
15 Example 

Draws a circle centered on the screen; two arcs with the same center but different radii; 
then a filled circle. 



20 



screen 


vga 


/graphics ,medi\im, color 


at 


320 


,240 


$$ set the center of the circle 


circle 


80 




$$ draw a circle with radius 80 


circle 


60, 


0,90 


$$ draw a quarter of a circle 


at 


320 


,240 


$$ reset the center" of the circle 


circle 


70, 


90,0 


$$ draw three-quarters of a circle 
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at 320,240 $$ reset the center of the circle ^ 

circle 40, fill $$ draw a filled circle in the center 

ciearu 

Removes unit(s) from the unit cache, 

5 ciearu [UNIT] 

ciearu SELECTOR: UNIT: UNIT:,,. 

Description 

Units are automatically loaded into a virtual memory central unit cache as they are 
needed, and deleted as necessary to make room for new units, ciearu can be used to manually 
10 clear specific units from the unit cache. 

The blank-tag form removes all but the current unit from the unit cache, 
ciearu clears only units loaded from a file of the type corresponding to the current mode 
of operation. See operate for a discussion of modes of operation. 

ciearu is affected by the edisk command. Because multiple copies of a single file may be 
1 5 present on different drives, there may be multiple copies of a single unit in the unit cache. If 
zedisk = -1, units are fetched by searching all drives. All units matching the lesson/unit 
specification in the tag of ciearu, and matching the current mode of operation (source or binary) 
are cleared from the unit cache, if zedisk ^A, then only a unit from the current execution disk is 
cleared from the unit cache. 
20 If no unit is cleared from the unit cache because no unit matched the unit reference and 

-mode of operation specifications, zreturn is set to -2. -If an attempt is made to explicitly clear the 
currently executing unit, zreturn is set to 19. 
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clearu is primarily used by utility programs to control which version of a unit is in ^ 
memory or to control which units are deleted to make room for others. 
System Variables 
zreturn 

5 -2 Redundant operation; no action taken 

-1 Operation successful 

19 Operation invalid, tried to clear the current unit 

clock 

Reads or writes system clock. 
10 clock time4 [ ,set ] 
Description 

Copies the information from the system clock into the specified 4-byte buffer. The set 
keyword sets the system clock to the time in the buffer. 

The system clock is stored as 4 bytes; one byte each for the hour, minute, second, and 
hundredths of a second. 
Example 

Reads the system clock and displays the current time in hours and minutes. 

define local 

sysclock, 4 $$ variables to hold time 

hours , 1 
minutes , 1 
seconds, 1 
hundrths , 1 

9S07007A2 I > 



20 
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define end ^ 

clock sysclock $$ read the current time 

at 5:5 

5 write The current time is: «t, hours, 2»:«t, minutes, 2») 



color 

Sets the foreground color, 

color COLOR 
10 color SELECTOR: COLOR; COLOR: ... 

xvrite «color \ c, COLOR» 

Description 

Selects the foreground color for subsequent text and graphics. 
The + at the end of a keyword indicates the bright version of the color. The keyword 
15 backgnd gives the background color (last specified with the colore command). A numeric 
expression evaluating to a hardware color number may be used in place of a keyword. 

Keywords set the first 16 colors (see the Command Syntax Description for keyword 
Colors). A color number must be used for colors coded higher than 15. 

The default foreground color is white. The default can be changed using color followed 

20 by status save; default. 

The color of text can also be changed by embedding text attributes into the tag of a write 

command. 
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CGA Restrictions 

When using any of the CGA graphics displays on a composite color monitor, turning the 
thickness option on (thick on) produces truer colors, 
screen cga, graphics, medium, color 

screen cga, graphics, medium, mono 

When using screen cga,graphics,medium, four separate groups of colors are 

available: 



1 


2 


3 


4 


backsnd 


backand 


backend 


backend 


areen 


areen+ 


cyan 


cyan-i- 


red 


red-f 


maaenta 


maeenta+ 


brown 


brown+ 


white 


white+ 



All colors on the display must be from one color group. If a color from one group is 
selected while colors from another group are on the display, all colors on the screen change to the 
10 corresponding color in the newly selected group. 
Example 

Displays yellow text in a blue box. 

screen vga 

color blue 

15 box 5:lO;lO:50 

color yellow 

at 6: 15; 10: 50 

write A paragraph of yellow text. . . 

System Variables 

20 zcolor Color number if set by a color keyword name; -1 if set by a color number 

zhcolor Hardware color number 
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colore 

Sets the erase colon 
colore COLOR 

colore SELECTOR; COLOR: COLOR;.., 
5 write «colore 1 ce, COLOR» 

Description 

Sets the erase color to be used for erasing, including: mode erase plotting, full screen 
erases, the erase command, and character background plotting in mode rewrite. To fill the 
screen or window with the erase color, a full-screen erase must be performed after execution of 
10 colore. 

The color keywords set the first 16 colors (See the Command Syntax Conventions). A 
color number must be used for colors coded higher than 15. 

A numeric expression evaluating to a hardware color number may be used in place of a 
keyword. 

1 5 On CGA graphics displays, colore is subject to the same color restrictions as color. See 

the color command description for details. On CGA text displays, bright colors (8-15) are not 
available for colore. 

The default erase color is black. This default can be changed using colore followed by 
status save; default. 
20 Example 

Erases the screen to blue after [ENTER] is pressed. 

screen vga 
color whi'te+ 
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at 5:5 

write Press Enter to see the background color change, 
colore blue 
pause pass= %enter 
5 erase 

at 5:5 

write The screen has been erased to change the 
background color. 

System Variables 

1 0 zcolore Color number if set by a color keyword; - 1 if set by a color number 

zhcolore Hardware erase color number 

compare 

Compares two text strings, 
compare string 1, string2, length, result 

15 string 1 the reference string, typically a variable or an up to 8-byte left-justified literal. 

string2 the compare string, must be in a variable, 
length number of bytes to compare 

result- 1 = identical; 0 = no match; >0 = last matching character. 
Description 

20 Compares two strings byte-for-byte. Variable boundaries can be crossed. The value 

returned into re^i/// indicates the success of the compare. If the strings partially match, result is 
set to the position of the last matching character. 
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In addition to result, compare sets zreturn to -1 if the strings match. If the strings jio not 
match, zreturn is set to indicate which string is "alphabetically" less than the other: 0 if the first is 
less, 1 if the second is less. The ASCII codes for the first characters that do not match will be 
compared to determine which string is "numerically" less. For instance, if "aaa" and "aab" are 
compared, zreturn will be set to 0 because the third character "a" of the first string is less than 
the third character "b" of the second string. 

System variables can not be used for either string. 
Example 

Checks a "password" before letting the user continue 

define local 

input ,8 $5 the user's entry 

password = 'Saturday* $$ today's password 

return ,2 $$ value returned by conipare 

define end 



15 



at 3:2 

write Enter the password of the day. . . 
long 8 
arrow 4 : 2 
20 zero input 
storea input 

con^iare password, input , 8 , return 
ok return 

write Good. Let's continue 

25 no 

write Sorry, wrong password. Erase and try again, 

endarrow 
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System Variables ^ 
zreturn 

- 1 First string = second string 

0 First string < second string 

5 I Second string > first string 

compute 

Computes the numeric value of a string of characters. 

compute string, length, result 

string text variable containing the characters to numerically evaluate 
10 length the number of characters to evaluate 

result numeric variable to hold the result of the compute 

Description 

Converts a string into a numeric value. The string may contain leading or trailing blanks, a 
leading + or • sign, and a decimal point. The string cannot contain any other operators. If the 
15 conversion is successful, the value is stored in result //"compute fails (zreturn =0), result 
remains unchanged. 
Example 

Converts a string to a numeric value, performs an operation on the value, then converts it 
back to a string: 

20 define local 

-string, 10 $$ holds the string "to convert 

length ,2 $$ length of the string 

number ,4,r $$ real ntiinber for result 
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$$ convert to numeric 



$$ convert to string 



pack string; length ;23.65 

coirpute string, length, number 

5 calc number c= number * 4.83 

packz string ; ; «show , nuinber» 

at 5:5 

write The new string is:«showa, string » 

System Variables 
10 zreturn 

- 1 Operation successful 

0 No valid number was found in the string 

1 Overflow error tr>'ing to store the converted number in the result variable. 

The result variable needs to be larger. 



15 date 



Reads or sets the current date. 



date date4 [ ,set ] 



Description 

Reads the date from the system clock and puts it in a variable. If the set keyword is used, 
20 the system date is set to the date stored in the variable. 

The system date is stored as 4 bytes; 2 bytes for year, 1 byte for month, 1 byte for day. 
Example 

Displays the current date. 
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define local 
today , 4 

year, 2, integer 

month , 1 , integer 
5 . day, 1 , integer 

define end 
★ 

date today 
* 

10 at 10:10 

write Today is $$$ 

writec month; ;; January ;February ;March ;April ;May ;June ; 

July ; August ; September /October /November /December ; 
write « show, day », «show,year». 

15 debug 

Turns step-by-step program execution on/off. 
debug on | off 

debug SELECTOR: on 1 off; on | off;... 

Description 

20 debug on stops execution of the current unit and enters the debugger. From the 

debugger, execution may continue either one command at a time (step mode) or until a specified 
command or unit is reached (breakpoint mode), debug off returns to normal execution. 
The debugging tool is exited by: 
• executing debug ofT 
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• pressing [ESC] to quit debugging ^ 

• exiting through the System Tools window 

• returning to the editor (normally via [SHIFT] [F2]) 

• an execution error 

5 debug is normally functional only during source mode execution. It can be made 

functional in binary mode by choosing that option when making the binary, debug does not 
function with the student executor. 

The debugger can also be entered while running a unit by pressing [SHIFT] [2]. then 
selecting Debug from the System key options menu. 

10 device 

Controls TenCORE device drivers. 

device device, function [ , variable [ .length ] ] 

device device number to call, in the range 0 to 255 
function device-specific function number to call, in the range 0 to 255 
1 5 variable data variable needed by the specified function 

length length of variable, if other than the defined length 

Description 

device allows authors to control hardware devices not directly supported by the 
TenCORE language, but which are implemented through TenCORE device support files. These 
20 include special mouse, touch-panel, and interactive video features which go beyond the standard 
support built into TenCORE commands. The variable tag is used only if the function requires a 
data variable. 
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Device Support FUes ^ 

To use device, a TenCORE device support file is required. The device support file is 
executed(loaded) before starting the TenCORE executor, and remains resident in memory. Usage 
of device depends on the device support file being addressed. 
5 System Variable 

zreturn 

Set to the processor register AL before returning. Some device support files use 
this feature to return status information. 

disable 

10 Disables system features (opposite of enable), 

disable keyword/s 





pointer 


disables pointer display and all pointer input 




ptrup 


disables pointer-up inputs 




cursor 


disables blinking cursor on text mode displays 


15 


arrow 


disables plotting of the arrow prompt 




absolute 


disables absolute screen plotting 




break 


disables break modified flow branching from interrupting processing 




area 


disables area input 




font 


plots characters from charsets instead of fonts 


20 


mode 


disables mode changes embedded in text 



Multiple features can be disabled by a single disable statement. See the Defaults section 
for the initial state of these system features. 
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Description ^ 
disable pointer 

Turns off display of the pointer and all input from the pointing device, 
disable ptrup 

5 Turns off button-up input from the pointing device. 

disable cursor 

Disables the blinking cursor for text mode screens. 

disable arrow 

Disables plotting of the arrow prompt character > and trailing space. User input occurs 
10 exactly at the location given in the arrow command, 
disable absolute 

Turns off the enable absolute plotting mode and causes subsequent screen graphics to be 
modified by scale, rotate, window, and origin commands, 
disable break 

15 Disables break modified flow branching from interrupting program execution, flow 

branching still occurs at the standard input processing locations (see the flow command for 
description), break is often disabled over a block of critical coding that must be completed in its 
entirety (e.g., file manipulations and their zreturn checks). Care must be taken to avoid disabling 
break while in a programming loop with no other means of exit. Since system routing keys such 

20 as [SHIFT][11 and [SHIFT][2] are turned off by disable break, a system hangup can occur, 
disable area 

Turns off area input. New areas can be defined while area input is disabled, but input 
from them will not occur until area input is enabled. 
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disable font 

*^ 

Plots characters from charsets rather than fonts. Charsets are an obsolete form of 
character definition, 
disable mode 

Turns off mode changes embedded in text. 
Defaults 

The system defaults for the enable and disable command features are set by the initial 
command to the following: 

ON area, arrow, break, font, mode 

OFF absolute, cursor, pointer, ptrup 

Status of Disable Features 

The current ON/OFF status of the system features affected by the disable command are 
found in the bitmap of the 4-byte system variable zenable. 



zenable BIT 


FEATURE 


1 


absolute 


2 


pointer 




mode 


4 


cursor 


5 


ptrup 


6 


font 


7 


area 


12 


break 


13 


arrow 
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Use the bit function to examine zenable. A bit set implies ON while unset implies OFF. 
For example: 

bit(zenable,2) = -1 means pointer ON 
bit(2enable,2) = 0 means pointer OFF 
5 Example 

All flow branching is turned off while attaching a file and checking for success. 

flow do; %flO; glossary; break $$ a flow break branch 



disable break 

10 attach 'afile'; nameset 

jump zreturn ; ;erroru 

enable break 



$$ prevent interruptions 
$$ attempt to open file 
$$ check success 
$$ re-enable flow breaks 



do 



Executes a unit as a subroutine. 



15 do UNIT[{ [argument/ 16s ] [ ; return/ 16s ] ) ] 

do SELECTOR: UNIT [ ( [ argument/ 16s ] [ ; return/ 16s ] ) ] ; 



20 



Description 

Executes the specified unit as a subroutine. Upon completion of the subroutine, execution 
resumes with the command following the do. Subroutines can be nested up to 20 levels deep. 

The unit which contains the do command is sometimes referred to as the calling unit; the 
subroutine is the called unit. 

If a jump branch to a new main unit occurs while in a subroutine, execution does not 
return to the conmiand following the do and the do stack is cleared. 
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do can pass up to 16 arguments to a subroutine and receive up to 16 arguments frotii a 
subroutine. A semicolon separates the send argument list from the receive argument list, while a 
comma separates arguments within a list. 

The called unit must accept the passed arguments with a receive command (unless a 
5 nocheck receive command is in effect) or an execution error will occur. The called umi must 
return any required return arguments using the return command (unless a nocheck return is in 
effect) or an execution error will occur. See receive, return, and no check. 

All arguments are passed and returned by value. However, the address of a variable can 
be sent as a value using the varloc ( ) function. 
10 Examples 
Example 1 

When writing courseware, it is advantageous to put displays and routines that will be used 
in multiple places into one place that can be called as a subroutine when needed. Unit header can 
contain coding for a title bar that will appear on all pages for this segment of the lesson. Unit 
1 5 diagram I can plot an image and other graphics that will be common for this segment of the 

lesson. The do call to unit navigate in lesson ioois is used to show the standard display of student 
navigation options available throughout all lessons in this series of lessons. 

header $$ in current lesson 

do diagraml $$ in current lesson 

20 at 20:10 

write This diagram shows the system we will be studying 
next at the start of its combustion cycle, 
-do tools , navigate $$ in lesson -tools 
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Example 2 

The do statement passes the value 3 to the subroutine month to request that it return the 
numerically identified month's name and number of days. The do command's argument list is 
divided into two parts separated by a semicolon: the first part is for sending arguments, the 
5 second part is for receiving arguments. 

define local 
najtie , 8 
days , 1 

define end 

10 do month (3; name, days) $$ get the name and days 

★ in the 3rd month 

write «a,name» has «s,days» days. 
★ 

unit month 
15 define local 
Inumber , 1 
Iname , B 
Idays , 1 
define end 

20 receive Inumber $$ obtain month number argument 

packzc Inumber; Iname ; ; ; ; January ; February ;Harch; April . 
calcs Inumber; Idays c= ;; 31; 28; 31; 30... 
return Iname, Idays $$ return the name and days 

Example 3 

25 The expression score < 75 is used as a true/false selector to choose either unit sad or 

smile which graphically shows a student's status with a sad or smiling face image. 

do score < 75; sad; smile 
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dot 

Plots a single pixel on the screen. 



dot [ LOCATION ] 



Description 

5 Plots a single pixel on the screen in the current plotting mode and color, at the specified 

location. If no location is specified, the current location (zx,zy) is used. 

The dot command is affected by thick. With thick on, all dots are plotted two pixels 
thick; with thick off, dots are plotted one pixel thick. 
Examples 
10 Example 1 

Displays a dot at the location of the mouse pointer (zinputx,zinputy) when the pause is 

broken. 

enable pointer 
pause pass= %pointer 
15 dot zinputx, zinputy 

Example 2 

Draws a sine wave using dot. 

define local 

^ $$ a real variable for the x-coordinate 

20 define end 
★ 

loop XC= 0,2*71, 0.1 

dot 50*x, 100+50*sin(x) 

endloop 
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System Variables ^ 

zx Current horizontal graphic screen location 

zy Current vertical graphic screen location 

draw 

Draws lines between screen locations, 
draw [LOCATION I [LOCATION]- [LOCATION]-,.. 



Description 

Plots lines on the screen in the current plotting mode and color. A line is drawn between 
each location separated by a semicolon. When a double semicolon (;;) is reached, draw skips to 
the next location. 

A single draw command can be continued on more than one line. If the tag starts with a 
semicolon, the line starts at the current screen location. 

With thick on, all dots are plotted two pixels thick; with thick off, dots are plotted one 
pixel thick. 
Examples 
Example 1 

Draws a box and a triangle on the screen with one draw command. Note the double 
semicolon to separate the two figures and that the drawing is continued over multiple lines, 

draw 10,10; 80,10; 80,100; 10,100; 10,10;; 10,130; 

100,130; 10,190; 10,130 
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Example 2 



Draws connected line segments at random locations on the screen (or window). The 
starting semicolon is used to start each draw at the current screen location which is the ending 
point of the previous draw. 



5 



loop 



color 



randi (1,15) 



$$ choose random color 



draw 



; randi (0 , zdispx) , randi (0 , zdispy) 



delay 



.01 



endloop 



10 ellipse 

Draws an ellipse, 
ellipse Xradhis, Yradiiis [, fill | angle 1, angle2 ] 
Description 

Draws an ellipse (or portion of an ellipse) with the center at the current screen location. If 
15 the fill keyword is specified, the ellipse is filled with the current foreground color. The current 
screen location is not altered after a full ellipse is drawn: multiple elhpses can be drawn with the 
same center without resetting the screen location. 

The two-tag form draws a full ellipse. The four-tag form draws only the arc of the ellipse 
specified by the starting and ending angles. Arcs are always drawn counter-clockwise from the 
20 first angle to the second angle. For example, ellipse 100,60,0,90 draws one quarter of an ellipse. 
The command ellipse 100,60,90,0 draws three-quarters of an ellipse. The current screen location 
is updated after an arc is drawn (a four-tag ellipse). 
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Example 

Draws an ellipse and two arcs centered on the screen. 

at zxinax/2, 2ymax/2 $$ set the center of the ellipse 

ellipse 95, 50 $$ <iraw a full ellipse 

ellipse 90, 40, 0, 90 $$ draw a quarter of an ellipse 

at zxmax/2, zymax/2 $$ reset the center of the ellipse 

ellipse 70, 30, 90, 0 $$ three-quarters of an ellipse 



else 



Alternate case for if/else programming structure. 



10 else 



15 



Description 

Should the conditions of the previous if and elseif commands be false, the indented 
commands between else and endif are executed. An else command is not required in an if 
structure. For more information on if structures, see the if command description. 
Example 



if score 
write 

elseif score 
write 

20 else 

write 

endif 



> 90 



> 75 



Very Good! 



OK, but you could do better. 



You need more practice. 



5 
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elself 

Conditional case for if/else programming structure, 

elseif CONDITION " " 

Description 

If the tags of the if command and all previous elseif commands evaluate false and the tag 
on the current elseif command evaluates true, the following indented commands are executed. 
Control then passes to the command following the endif For more information on if structures, 
see the if command description. 
Example 

10 if score > 90 

write Very Good! 

elseif score > 75 

write OK; but you could do better. 

else 



1 5 . write 
endif 



You need more practice. 



enable 

Enables system features (opposite of disable). 



enable keyword/s 
20 enable «vadable4» 

* pointer turns on pointer display and pointer input 

ptrup enables pointer-up inputs 

cursor turns on blinking cursor on text mode displays 
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arrow re-enables plotting of the arrow prompt ^ 

absolute turns on absolute screen plotting 

break re-enabies break modified flow branching to interrupt processing 

area re-enables area input 

5 font re-enables font plotting 

mode re-enables mode changes embedded in text 

Multiple features can be enabled by a single enable statement. See the Defaults section for the 
initial state of these system features. 

Descriptions 
10 enable pointer 

Turns on display of the pointer and input from the pointing device. 

enable ptrup 

Enables button-up input. Unless ptrup is enabled, the pointing device generates input 
only when a button is depressed 
15 enable cursor 

Turns on a blinking cursor for text mode screens. This command has no effect on graphic 
screens, 
enable arrow 

Re-enables plotting of the arrow prompt character > and trailing space. 
20 enable absolute 

Turns on absolute screen plotting mode. Subsequent screen graphics are not modified by 
scale, rotate, window and origin commands. The scale, rotate and origin commands are 
effectively turned off while window becomes modified by relative off and clip off. 
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enable break ^ 

Re-enables break modified flow branching to interrupt program execution, 
enable area 

Re-enables area input. Any previously defined current areas including those defined while 
5 area input was disabled are now active, 
enable font 

Returns to using fonts instead of charsets for character plotting. Charsets are an obsolete 
form of character definition, 
enable mode 

10 Re-enables mode changes embedded in text, 

enable «variable4» 

The variable form of the enable command is used to enable/disable all features according 
to their bit settings in a 4-byte variable. The variable is usually a saved copy of the system 
variable zenable that is used to later reset all features back to a previous state. The feature 
1 5 bitmap is discussed in the following section Status of Enable Features. 
Defaults 

The system defaults for the enable and disable command features are set by the initial 
command to the following: 

ON area, arrow, break, font, mode 

20 OFF absolute, cursor, pointer, ptrup 

Status of Enable Features 

The current ON/OFF status of the system features affected by the enable command are 
found in the bitmap of the 4-byte system variable zenable. 
zenable BIT FEATURE 
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1 


absolute 


2 


pointer 


-» 


mode 


4 


cursor 


5 


ptrup 


6 


font 


7 


area 


12 


break 


13 


arrow 



1 0 Use the bit function to examine zenable. A bit set implies ON while unset implies OFF. 

For example: 

bit(zenable,2) = -1 means pointer ON 
bit(zenable,2) = 0 means pointer OFF 
Example 

1 5 The absolute screen coordinates of the pointer are displayed at the pointer location. The 

coordinates and display are relative to the physical screen and not affected by any window, 
origin, rotate or scale commands. 

enable pointer , absolute $$ turn on pointer and absolute 

20 loop 

$$ move mouse then press button 
zinputx , zinputy S$ at pointer location 
<s,zinputx» - <s,zinputy» $$ show coordinates 

endloop 



pause 
at 

write 
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endif 



Ends if/else programming structure. 



endif 



Description 

5 Marks the end of an if structure. Every if must have a matching endif at the same indent 

level. For more information on if structures, see the if conamand description. 
Example 



if score 
wri te 

10 elseif score 
write 

else 

write 

endif 



> 90 



> 75 



Very Good! 



OK, but you could do better. 



You need more practice. 



15 endloop 



Ends loop programming structure. 



endloop 



Description 

Marks the end of a loop structure. Every loop must have a matching endloop at the same 
20 indent level. For more information on loop structures, see the loop command description. 
Example 

Fifty X's are written on the screen. 
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loop 



index 



c= 1,50 



write 



X 



endloop 



erase 



5 



Erases a box, frame or characters on the screen. 



erase [ LOCA TION ] [; [ LOCA TION ] [; Xframe [, Yframe ]]] 



Description 

Erases a box or frame on the screen to the background color. See the Command Syntax 
Conventions for a description of LOCATION. The box command is identical to erase except that 
10 it uses the foreground color for drawing. 



erased. The widths of the right and left sides are specified in pixels by the first frame argument 
while the second frame argument specifies the top and bottom widths. If the second frame 
argument is absent, the top and bottom frame width is set to best match the side width in aspect 
1 5 appearance on the screen. 



colore blue 
20 erase 

Example 2 

A rectangle 200 pixels wide by 100 pixels high is erased to the background color. Graphic 
coordinates are used to specify each x,y coordinate for a location. 



The presence of a frame width argument signifies that a frame rather than solid box be 



Examples 



Example 1 



The entire screen (or window) is erased to blue. 
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erase 101,101; 300,200 
Example 3 

The text in a write statement is later erased after a pause. The text measure command is 
used to determine the screen area that a following paragraph of text plots over on the screen. 
5 This information is returned in the system variables zplotxl, zplotyl for lower left corner and 
zplotxh, zplotyh for upper right corner. 

text measure $$ initialize text measuring 

at 100,150 
10 write This is a paragraph of text of arbitrary 
length that will be erased. . . 

* 

pause 

erase zplotxl , zplotyl; zplotxh, zplotyh 

15 Example 4 

Ten characters are erased, 
at 10:1 
erase 10 

error 

20 Specifies an execution error unit. 

error [UNIT] " ' 

error SELECTOR ; UNIT ; UNIT;,.. 
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Description ^ 

Sets the execution error lesson and unit. Whenever an execution error occurs, the system 
jumps to the unit specified with error. If no unit has been specified, a TenCORE system error 
message is displayed. 

5 The blank-tag form clears the error lesson and unit. The setting of the error unit remains 

in effect until another error command is encountered. 

The "error unit" is normally set by the router lesson when the system is started. 
When error is executed, the current mode of operation, (binary or source), is saved along 
with the error lesson and unit names. If an error causes a branch to the error unit, the saved mode 
10 of operation is used to decide whether to fetch the error unit from a binary file or a source file. 
System Variables 

zerrorl Name of the error lesson 

zerroru Name of the error unit 

exchang 

1 5 Exchanges the contents of two areas of memory. 

exchang keyword, offset; keyM^ord, offset; length 

keyword routvars 1 r Router variables 

display Id CGA screen display memory 

global 1 g Global variables 

2Q local 1 1 Local variables 

sysvars 1 s System data area 

sysprog 1 p System program area 

absolute 1 a Absolute memory location 
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offset offset from memory base 
length number of bytes to exchange 



Description 

Exchanges bytes between two areas of memory. Up to 65,535 (64K-1) bytes can be 
5 exchanged. An offset of 0 specifies the beginning of the area of memory. 

For relative addressing, TenCORE divides the computer memory into areas, each with its 
own keyword. A location is specified by providing a keyword, then an offset An offset of 0 
specifies the first byte of that area. 

Additional information about each keyword: 
10 routvars This is a 256-byte area of memory which can be accessed only via exchang 

and transfr. This area is used by the Student Router for storing data while a 
user is in an activity, if using this router, be careful not to modify the first 128 
bytes of this area. 

display CGA screen display memory. The display memory for other display types 
15 (EGA, VGA etc.) cannot be accessed with exchang. 

sysvars Do not use this area for data storage, 
sysprog Do not use this area for data storage. 

absolute Programs which reference absolute memory locations may not work in multi- 
tasking environments. 

20 Because exchang can access any area of memory in the computer, it should be used with 

caution. 

When specifying an offset in variables, the varToc( )function can be used to specify the 
offset of a particular variable. 
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Similarly, an absolute memory location can be specified using the absloc( ) functionr 
Note, however, that abslocQ may not work properly on multi-tasking operating systems such as 
Windows or OS/2. 

Locally defined names have precedence over globally defined names when using varloc( ). 
5 This could cause unexpected resuhs when varloc( ) is used with exchang. 
Examples 
Example 1 

The expression varloc(scon^ar) specifies the beginning of global variables containing user 

scores, 

10 exchang global, varloc (scorvar) ; routvars . 128 ; 128 
* Uses 2nd half of routvars 

Example 2 

Makes certain that the 2-byte value \nXO is less than or equal to the 2-byte value in 
XL 

15 if xo > XI 

exchang global, varloc (XO) ; global , varloc (Xl) ;2 

endif 

exec 

Executes a DOS program or command. 

20 exec keyword... 

command executes a program or command through the DOS command processor, o 

provides access to the DOS proinpt 

nie executes a program directly 
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Descriptions ^ 
exec command [, all | memorySize ] 

Provides access to the DOS command line prompt. To return to TenCORE, type exit at 
i the DOS prompt. 

5 DOS memory not currently used by TenCORE is available for use by programs or 

commands entered at the DOS prompt. If the all option is specified, as much DOS memory as 
possible is made available by temporarily removing most of TenCORE. If a memory size is 
specified, the system attempts to free the specified number of kilobytes of memory. Note that the 
DOS command processor uses a part of this memory. 

10 exec command [, all | memorySize J; buffer [, length ] 

The DOS command processor is loaded and passed the buffer to execute as if its contents 
had been typed at the DOS prompt. Features of the DOS prompt such as path search and batch 
file execution are available. If the length is not specified, the defined length of the buffer is used; 
unused bytes at the end of the buffer should be zero-filled. 

15 DOS memory not currently used by TenCORE is available for use by the passed program 

or command. If the all option is specified, as much DOS memory as possible is made available by 
temporarily removing most of TenCORE. If a memory size is specified, the system attempts to 
free the specified number of kilobytes of memory. The DOS command processor uses a part of 
this memory. 

20 exec file [ ,all | memorySize j; buffer [Jength ] 

Executes .EXE and .COM files (only). The complete file name (including the .EXE or. 
^ COM extension), as well as drive and path must be specified. The features of the DOS command 
processor such as path search and batch file execution are not available. Any characters starting 
with the first space or slash (/) are passed as arguments to the executed file, if the length is not 
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specified, the defined length of the buffer is used; unused bytes at the end of the buffer shontd be 
zero-filled. 

DOS memory not currently used by TenCORE is available for use by the executed file. If 
the all option is specified, as much DOS memory as possible is made available by temporarily 
5 removing most of TenCORE. If a memory size is specified, the system attempts to free the 
specified number of kilobytes of memory. 

The file form of exec is more efficient than the command form as the DOS command 
processor is not loaded. This form also allows access to error reports for the executed program 
(the command form provides error reports for the DOS command processor). 

10 Examples 

The following defines are used for all the following examples. 

define local 
buf, 100 
define end 

15 Example 1 

Uses the command form of exec to allow any DOS directive or program name typed at 
an arrow to be executed. As much memory as possible is made available. 

write Enter DOS command to execute: 
long 100 
20 arrow 

storea buf $S store input into variable 

ok 

endarrow 
- exec command, all ; buf 

25 writec zreturn; ; Error: zreturn = «showt , 2return» 
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Example 2 



Uses the command form of exec to copy all TenCORE datasets in the current directory 
to drive a:. As much memory as possible is made available. 



packz 



buf ; ; xcopy * . dat a : 



exec 



command, all ;buf 



writec zreturn ; ;Error : zreturn = «showt , zreturn» 
Example 3 

Uses the file form of exec to call the Autodesk Animator animation program 
OUICKFLLEXE in directory DrPROGS to play the animation BACKHOE.FLI in directory 
C:''ANIMS. 250 kilobytes of memory are requested, 
s cr een mega , medi-uin 

packz buf ; ; d : \progs\quickf li . exe c : \anims\backhoe . f li 
exec file,250;buf 

writec zreturn ; ;Error: zreturn = «showt , zreturn» 

System Variables 

The exec command sets the following system variables. 

command form: 
zreturn reports on success of operation 



DOS command processor successfully executed. 



0 



insufficient memory to load DOS command processor, or unable to 



provide requested amount of memory. 



DOS command processor (C0MMAND.COM) not found. 



file form: 



zreturn reports on success of operation 



-1 



program successfully executed 
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0 insufficient memory to load program, or unable to provide requested^ 

amount of memory. 

1 program no found. 

zerrlevl DOS ERRORLEVEL value as returned by executed program. 
5 Both forms also set the system variables zedoserr and zerrcode which provide extended 

DOS error information. 

exitsys 

Exits to DOS or to the program which called TenCORE. 

exitsys [ error [ ,noerase ] ] 
\Q error 1-byte integer value passed to the DOS variable ERRORLEVEL 

noerase the screen mode is not changed and the screen is not erased 

Description 

Returns control back to the program which called the TenCORE executor. Normally, the 
user is returned to the DOS prompt. If TenCORE was started via a DOS batch file, the next 
1 5 command in that batch file is executed. If error is specified, the value is passed to the DOS 

variable ERRORLEVEL, where it can be tested using DOS commands. If the noerase keyword 
is present, the screen mode is not changed and the screen is not erased. This keyword can only be 
specified when using the return value error 
ERRORLEVEL Values 

20 TenCORE uses ERRORLEVEL values to indicate various error conditions. Authors are 

advised against using values 0 to 3 1 with exitsys. 

0 Normal exit via exitsys (no tag) 
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1 Copy protection violation 

2 Error in TenCORE command line options 

3 Insufficient memory to execute TenCORE 
• 4 Display driver not found 

^ 5 Error in display driver (e.g., invalid revision number) 

6 Error in syntax of TenCORE environment string 

7- 1 5 Reserved for later use 

16 Initial unit not found 

_ 1 7 No startup found in first unit executed 

10 18 Initial unit version incompatible with executor 

19 All drives excluded by TCDISKS or TCSEARCH 

20-30 Reserved for later use 

3 1 [SHIFT][7] pressed from generic Execution Error display 

extin 

15 Reads data from an external I/O port. 

extin port, buffer, length 

port address of the I/O port to read from 

buffer buffer to receive data from the port 

length number of bytes to receive 



20 Description 

Reads the specified number of bytes from the specified external I/O port. This command 
can be used to control external devices via a serial or parallel port. Consult the IBM Technical 
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Reference Manual for details on addressing and controlling the serial and parallel ports, extatit is 
the counterpart to extin. 

Examples 

Example 1 

Reads one byte of data from COMl. 

define local 
r status , 1 
define end 



$$ the variable to read into 



10 extin 1016,rstatus,l 

♦ read 1 byte from address 1016 (h3F8) into rstatus 

Example 2 

Uses extin and extout to send a byte to the COMl port using xon/xoff protocol. This 
routine could form the basis of a routine to control a printer. 

15 define local 

status ,1 $$ status flags for coml : 

^ ^1 $$ data ready, bit 0 of the status bits 

* if this bit is set, there is data ready to read 
rstatus ,1 $$ a character read from coml: 

20 tx ,1 $$ transmitter status. If 0, the port is 

* ready to accept another character to transmit 
xonoff ,1 $$ xon/xoff flag. If 1, xoff, else xon. 
char ,1 $$ a character to send out the port 



25 Isr 



rxvar 
txvar 



1021 
1016 
1016 



S$ line status register address 

$5 receive variable register address 

$$ transmitter variable register address 
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define end 
* 

loop 

loop 

5 . . extin Isr, status,! 

* • now check the first bit of the status, 

* . see if xon/xoff was sent 

calc dr c= status $mask$ 1 

outloop dr = 0 $$ no xon/xoff, so proceed 

10 * if there was xon/xoff, read it and set the flag 

extin rxvar , rstatus , 1 

calcs rstatus=17; xonoff c= 0 , 1 

endloop 

reloop xonoff =1 $$ xoff , so loop again 

15 * now check bit 5 of the status to see if it's ok to send 

* another character 

calc tx c=z status $mask$ 32 

outloop tx=32 $$ if ok, send it, otherwise loop again 

endloop 

20 extout txvar,char,l $$ send the charactei 



sr 



extout 

Writes data to an external I/O port 



extout port, buffer, length 

port address of the 1/0 port to write to 

25 buffer buffer containing the data to send to the port 

length number of bytes to send 
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Description ^ ^ 

Writes the specified number of bvtes to the specified external 1/0 port. This command 
can be used to control external devices via a serial or parallel port. Consult the IBM Technical 
Reference Manual for details on addressing and controlling the serial and parallel ports, extin is 
5 the counterpart to extout. 
Examples 
Example 1 

Writes the contents of rstatus to COMl. 

define local 

10 rstatus ,1 

define end 
★ 

extout 1016, rstatus, 1 $$ writes rstatus to COMl (h3F8) 

Example 2 

15 See the extin command description. Example 2 for an additional example. 

fill 

Fills any bounded area on the screen. 

fill [ color [, boundary ] ] 

color color to fill with 
20 boundary color which defines the boundary of the area to be filled 



BNSDOCtD <wo qqn7on7A5 i > 



wo 99/07007 PCT/US98/15627 

241 

Description ^ 

Fills an enclosed area with a specified color starting at the current cursor position. If no 
color is specified, the area is filled with the current foreground color. If no boundary color is 
specified, the fill stops at any color different from the original color of the beginning point. 
5 If the area to be filled is not closed the entire screen is filled. 

The fill command usually follows an at, which sets the point at which the fill is to begin. 
Fill does not use the current plotting mode: the specified color always appears regardless 
of mode. 

Example 

10 Produces a red circle inscribed with a bright white triangle outline. After the first delay, 

the top segment of the triangle is filled with cyan. After the second delay, the top segment 
becomes magenta. After the last delay, the entire triangle becomes solid blue with a white outline. 

screen vga 

color red 

15 at 320,216 

circle 65, fill 

color whiter- 
draw 320,335; 200,150; 440,150; 320,335 

delay 1 

20 color cyan 

at 320,334 

fill 

delay 1 

fill magenta 

25 delay 1 

fill blue, white+ 
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find 



Finds the position of a data object within a list. 



find object, length, buffer, entries, incr, return 

object data to search for 

length length of the object in bytes 

buffer variable to begin search 

entries number of entries in list 

incr length of each entry in buffer in bytes 

return entry number of first match 



10 Description 

Searches a list of character or numeric entries for the desired object string, find will 
search for the object every incr bytes, from the beginning of buffer without attention to defined 
sizes or boundaries of variables. It considers buffer to be the first byte of a list whose 
characteristics are defined entirely by entries and incr. 
15 Uincr is negative, the search proceeds backwards from the end of the list to the start. 

return indicates the position in the list where object was found, with the first entry being 
1 . If the object is not found, -1 is returned. The value in return is always relative to the beginning 
of the list, even if the search is backwards. 
Examples 

20 The examples below all assume the following defines. 

.define local 

name, 15 $$ name to search for 

found, 2 $$ position in list where "name" found 
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list (5), 15 $$ list of names ^ 

define end 

In each example, list contains 5 names, each of which occupies 15 characters. The 
contents are as follows: 

5 John miller. . . .mark ho sarah johnston. james hef lin. . .lisa berger, 

t t t t t 

1 16 31 46 61 

Null characters have been shown as dots to improve their visibility, and numbers have 
been added to help in counting bytes, 
10 Example 1... Literal Object 

Searches for the name 'mark ho'. 

find 'mark ho • , 7 , list ( 1) , 5 , 15 , f ound $$ found will be 2 

Because the name has 8 or less characters, it can be supplied as the text literal 'mark ho'. 
Next comes the length, 7 characters. The start of the list is given as list(l), and its length as 5 
15 entries of 15 bytes each. 

After tht searchjound contains the value 2 because 'mark ho' is found at the second 
position (not the second byte) in the list. 
Example 2...VariabIe Object 

Objects of more than 8 bytes cannot be given as text literals and must occur in variables. 
20 To locate 'james heflin': 

packz name;; james heflin 

find name, 15, list (1) ,5, 15, found 

The vaiiablQ found receives the value 4 because james heflin' is found in the fourth 
position. 



BNSDOCia <WO 9907007A? I > 



wo 99/07007 PCT/US98/15627 

244 

Example 3,..Byte-by-Byte ^ 

To find a last name. 

packz name; ; miller 

find name,6,list(l> ,75,1, found 

5 When this example is txtcwi^^Joimd receives the value 6. 

Note that the length of the name is given as 6 because this locates part of an entry, not an 
entire entry. 

Similarly, the list is specified as 75 one-byte entries instead of 5 fifteen-byte entries. This 
causes find to look for 'miller' starting at every byte, not just at the start of each 15-byte entry. 
10 This illustrates that the object of the search can be longer than the nominal entry length provided 
for it. 

Example 4.,.Backwards Search 

To search backwards, a negative value is given for the entry length. This searches 
backwards from the end of the list for 'john', looking only at the beginning of each 15-byte entry. 

15 find ' john' ,4,list(l) ,5, -15, found 

Here, found receives the value 1 . Although the search proceeded backwards from the end 
of the list, the position is always counted from the beginning of the list. 
Example 5...Backwards Byte-by-Byte 

Another example of backwards searching is the following. 

20 find • john* ,4,list(l) ,75,-1, found 

In this case, an entry length of -1 is used, causing find to look at every character starting 
from the end of the list. 

found receives the value 37, because the first 'John' found when searching backwards byte- 
by-byte occurs in 'sarah johnston'. If the search had been in the forward direction, 'john miller' 
25 would have been found first, and found would have received the value 1 . 
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flow 

Manages lesson now by event-driven unit branching. 



5 



10 



flow keyword... 




jump 


defines event driven unit branch with screen erase 


jumpop 


like jump but without screen erase 


do 


defines event driven subroutine call 


library 


like do but forces a binary subroutine call 


clear 


clears active flow event settings 


save 


saves active set of flow events 


restore 


restores saved set of flow events to active status 


delete 


deletes saved set of flow events 


reset 


deletes all saved sets of flow events 


dir 


returns list of active flow events 


info 


provides flow branch data about active flow event 



15 Description 

Manages event-driven branching. Events can be keypresses, pointer inputs, time-ups, etc. 
A specific event can trigger a jump to a new main unit or a subroutine call. 

Up to 50 different events can be active at a given time. A set of flow events and 
associated branches can be defined as the default environment for all new main units throughout i 
20 lesson. Advanced options can manipulate a lesson's flow settings so as to provide a clean 
• connection to a router or library routines. 

Flow events normally occur at waiting states within a lesson: 
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• at a pause that allows flow key input ^ 

• at an arrow that processes user keypresses 

• at the completion of a unit's execution ("end-of-unit") 

A sequence of coding will not be interrupted by a flow event at any other place unless the 
5 flow definition has been modified with break to allow for program interruption, 
flow jump I jumpop | do | library; KEY/s; UNIT [modifier; modifier;*..! 

Defines a connection between a keypress (or other input event) and a branch to a unit. 
The first argument is a keyword specifying the type of branch. KEY is described fully in the 
Syntax Conventions section. Multiple keys separated by commas are allowed and when pressed 
10 cause a branch to UNIT, A total of 50 different events can be active as created by multiple flow 
conmiands. A given event is associated with one branch at a time. If the same event is defined in 
two different flow commands, the most recent definition takes precedence. Modifiers alter the 
standard operation of the command. Argument passing is not supported, 
jump 

15 Ends the current unit and branches to a new main unit. The following initializations are 

performed: 

• the screen is erased to the default background color 

• all flow events and area definitions are cleared and reset to their main unit defauhs 

• all display parameters are reset to their main unit defaults (as set by status save; default) 
20 • the unit becomes the new main unit for processing and flow events 

jumpop 

Ends the current unit and branches without a screen erase ("op" stands for "on page") to a 
new main unit. Only the following initializations are performed: 
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• all flow events are cleared and reset to their new main unit defaults ^ 

• the unit becomes the new main unit for processing and How events 
do 

Calls a unit as a subroutine. No initializations are performed. Return from the subroutine 
5 unit continues execution at the place the flow do event occurred, 20 levels of nested subroutine 
calls are allowed, flow do executes in source or binary mode depending on the mode of the 
calling lesson, 
library 

Calls a unit as a binary subroutine. No initializations are performed. Return from the 
10 subroutine unit continues execution at the place the flow do event occurred. 20 levels of nested 
subroutine calls are allowed, flow library is frequently used for calling third party software where 
the coding exists only in binary form. 
Example 1 

When [ENTER] is pressed, branches and passes control to quizl in the current lesson. 
15 The screen is erased and all display settings, flow branches, and pointer areas are reset to their 
main unit defaults. When [F8] is pressed, moreinfo is called as a subroutine and control remains 
with the calling unit. Unit moreinfo would contain coding to add new information to that already 
on the screen. 

write Press Enter to Begin the Quiz. 
20 Press F8 for more information, 

flow jtimp; %enter; quizl 

flow do; %f8; moreinfo 
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Example 2 ^ 

Branches and passes control to unit index in lesson aerol when either [Fl] or [ESC] is 
pressed- When [PGt] is pressed, the binary subroutine scroll is executed. Control remains in the 
calling unit upon return from scroll 

5 flow jurrp; %fl,%esc; aerol, index 

flow library; %pgup; scroll 

Example 3 

Branches to the unit named by the variable uyniVar when any of the keys a, b, c or the 
value contained in the variable xkey is input. 

10 flow juirp; a,b,c, «xlcey» ; «unitvar» 

Example 4 

Branches with a screen erase to help when either [Fl] is pressed or a Click occurs on the 
associated area. Pressing [F2] or a Click on its associated area branches to more without a screen 
erase. In either case, control passes to the new unit, 

15 area define; 100,0; 150,20; click=%fl 

area define; 200,0; 250,20; cliclc=%f2 

flow jturp; %fl; help 

flow juitpop; %f2; more 

Generic Unit Names 

20 Generic branch names are provided for common jump destinations to new main units: 

=next The next physical unit to the current main unit in the lesson. If none, the 

branch is ignored. 

=back The previous physical unit to the current main unit in the lesson. If none, 

the branch is ignored. 
25 =rirst The first executable unit in the current lesson. 
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=Iast The last executable unit in the current lesson. ^ 

=nriain The current main lesson and unit as held in the system variables 

zmainl,zmainu. 

=base The main lesson and unit from which the last base modified flow branch 

5 occurred or as set by the base command. If none, the branch is 

ignored. The names of the current base lesson and unit are held in the 
system variables zbaseUbaseu. Typically used for returning from a 
supplementary lesson sequence such as help to the main line of study. 
See base modifier on page SSS. 
10 =editor The Source Editor (with the current executing unit as the source block 

being editied) if executed by the authoring system; ignored by the 
student executor. 

=exit The lesson exit as set by the exitles command and contained in the system 

variables zexitl,2exitu. Student users are typically branched back to 
1 5 their routing system such as the TenCORE Activity Manager or DOS 

if none is present. An author testing a lesson is returned to the File 
Directory. 

=systeni Opens the system options window with the calculator, image capture, 

cursor, etc. [F2] is normally loaded with this branch as a TenCORE 
20 system default during authoring; ignored by the student executor. 

Example 1 

Branches to the unit following or preceding the current main unit in the lesson when 
[ESC] or [F6] is pressed. In the first or last unit of the lesson, the branch is ignored. This is an 
easy way to program the essential flow for a linear page-turning lesson. 
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flow 



juicp; 



%enter ; =next 



flow 



%f6; =back 



Example 2 

When [ESC] is pressed, branches to the exit unit that was specified by the exitles 
5 conunand in a router or, if none, then DOS. 



Unanticipated Input 

A flow event can be defined for all unanticipated input at one of the natural waiting states 
by using the pseudo-key %other. This "other" event occurs only if the input cannot be applied to 
10 any other possible flow branch or input situation. 
Example 1 

Causes any key inputs that would otherwise be discarded by the system to branch to unit 
record which, say, records these unanticipated inputs for later study. 

flow do; %other; record; default; break 

15 Example 2 

At the pause, keys a, b and c continue execution of the unit. Any input specified in an 
active flow event such as [ENTER] and [F6] work as defined. Any other inputs branch to unit 
contimie. 

flow junip; %enter; =next 

20 flow jun?); ftfS; -back 

flow jxainp; %other; continue 

.pause flow=all ;pass=a,b,c 



flow 



jump; %escape; =exit 
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Example 3 ^ 
At the arrow, standard ASCII input such as a, b and c cause typing to appear on the 

screen as expected. Other arrow related functions such as erase, copy, judge-with-the-Enter key, 

■I- 

etc. also perform as expected. Any defined flow event such as the branch to unit aha is active; 
5. unanticipated keys such as an undefined [F12] branch to unit help 

flow do; % other; help 

flow juirp; %f3; aha 

arrow 10:20 
10 Modifiers 

Modifiers on a flow statement alter the default action of the command. Multiple 
modifiers separated by semicolons can be used and in any order although some are 
mutually exclusive. 

default Establishes the flow branch as a default setting for all subsequent new main 
15 units, default modified flow settings are cleared by an initial statement or 

by a flow clear statement with a default or router modifier, default 
settings for an entire lesson are often placed in the +initial control block of 
a lesson so that they are set with any entry to the lesson, 
complete Delays putting the flow command into effect until all processing in the unit 
20 is completed including any pause or arrow statements. The flow works 

only at the end-of-unit. For example, users can be required to complete all 
arrows in a unit before branching to the next unit. The complete and 
. break modifiers cannot be combin.ed. 
router Establishes the flow setting permanently over all following units. It is NOT 
25 cleared by an initial statement The router modifier allows management 
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software (such as the TenCORE Activity Manager) to permanently set ^ 
keys for routing use in an application, router flow settings can be cleared 
only by using flow clear with the router modifier 
For example, a router modified exit branch using [SHIFT][l] is set by the 
TenCORE system at start-up of the student executor to return users to 
DOS. If the Activity Manager is used, it resets this flow branch to exit 
users back to a return unit in the Activity Manager before launching an 
application. 

Great care should be taken in clearing router flow settings in an 
application lesson as the user can become stuck in the application. The 
router and break modifiers are best used together unless you are certain 
that your lessons accept the router exit key in all situations, 
break Allows the flow branch to occur at any point, interrupting any 

programming or pause in process. A break modified flow branch will 
always work unless temporarily turned off by disable break. The main use 
for break is to interrupt a programming loop that does not check for keys. 
The break modifier is often used with the router modifier by a router to 
guarantee that the exit branch will always work in application lessons, 
break cannot be combined with complete. 
When a break modified flow do or flow library event interrupts 
commands being processed (as in a programming loop), the current 
program statement is completed, the subroutine is executed, then 
processing continues with the next statement. When a break occurs at a 
timed pause or delay conunand, the timing is suspended until return from 
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the subroutine. During the subroutine call, the flow event is temporarily^ 
disabled to avoid recursion and re-enabled upon exit from the subroutine. 
In addition, the following system variables are saved and restored over the 
subroutine call: zinput, zinputf, zinputx, zinputy, zinputa^ zreturn. 
Great care must be taken to avoid unreliable results when using break 
with the do or library form of flow. Since a break interrupt can occur 
anywhere, variables (especially system variables) can be accidentally 
changed in the interrupt do or library call level making them invalid upon 
return from the call The break attribute should be turned off over critical 
coding by use of a disable break statement. See the following Example 4. 

clearkeys Upon branching, deletes all pending input from the input buffer, clearkeys 
eliminates keys that may have been "stacked-up" waiting for some event to 
end, such as a lengthy full-page display. 

base ■ The base modifier on a flow branch causes the main lesson and unit from 
which the branch occurs to become the base lesson and unit and stored in 
the system variables zbasel and zbaseu. When a base modified flow 
branch initiates a supplementary lesson sequence, such as help, the =base 
generic 6W7riocation can be used to return the user to the starting base 
location. 

windowclose Closes the current window, if any, before executing the flow 
branch. 

windowreset Closes all open windows, if any, before executing the flow branch, 
operate Before branching, restores the execution mode in effect when the flow 
statement was encountered. (See the operate command.) 
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binary Before branching, changes to binary execution mode ^ 
source Before branching, changes to source execution mode, 
tpr Before branching, changes to tpr (Producer) execution mode. 

Example 1 

5 Causes an immediate branch to the next linear unit in the lesson when the [ENTER] key is 

pressed. All subsequent main units will default to this flow setting. If this statement is to apply to 
the entire lesson, it should be placed in the +initial control block 

flow j«n?>; %enter; =next; default; break 

Example 2 

10 Sets [ESC] to be a router exit key. It is kept permanently over initial commands and will 

' break any programming situation (unless break is disabled), close all windows, and jump to 
route, return. 

flow j^iwp; %escape; route , return ; router; break; windowreset 

Example 3 

1 5 Branches to unit ques6 if [ENTER] is pressed at an end-of-unit. Any pause or arrow 

must be completed first. Any other inputs "stacked-up" are removed. 

flow juii?>; %enter; ques6; coit^slete; clearkeys 

Example 4 

A library unit (clock in lesson routines) is installed to show the user the time whenever 
20 [F 1 0] is pressed or when a %timeup input occurs. Within the library routine itself, a time 1 
statement is executed before exiting so that the %tiraeup key will keep occurring and "refresh" 
the clock every second while the user remains in the main unit. Critical coding in the lesson that 
may be affected by unexpected interrupts should be protected by disabling the break attribute 
over the coding, then enabling it again after the coding. 
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flow library; %f 10 , %timeup ; routines , clock ; break; default 

disable break $$ protect critical coding 

attach 'file* ;naineset $$ perhaps unit clock also does attach 

do zreturn; ;erroru 

setname 'block* $$ and setname 

enable break $$ re-enable break 

flow clear ( ; [ KEYS/s J [; default | router ] 1 

Deletes flow settings from the active list and optionally from the new main unit default 
and the router lists. The default modifier is used to remove any flow definitions that have been 
set with the default modifier. The router modifier is used to remove both router and default^ 
modified flow settings. 
Example 1 

Deletes all active flow settings except those modified with router. Any settings made with 
the default modifier will be re-activated upon a jump to a new main unit. 

flow clear 

Example 2 

Deletes any active flow settings for [ENTER] and [F6] unless they were defined with the 
router modifier. If either of these keys were defined with a default modifier, it will be re- 
activated upon a jump to a new main unit. 

flow clear; %enter,%f6 

Example 3 

Deletes [ENTER] from the active and default flow settings unless it has the router 
attribute 
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flow clear; %enter; default ^ 

Example 4 

Deletes all flow settings, except those modified with router, from both the active and 
default settings. An initial statement also performs this task. 
5 flow clear; ; default 
Example 5 

Completely deletes [ENTER] as a flow setting regardless of how it was set. 

flow clear; %enter; router 

Example 6 

10 Deletes all flow settings regardless of how they were defined. Use with extreme caution 

for all the system flow settings such as [SHIFT][F1] are also removed preventing any exit unless 
otherwise provided for. 

flow clear ; ; router 

now save;'NAME' | local 

15 flow save; default 

Saves the set of active flow definitions in a memory pool block or the default buffer. The 
name can be either a text literal or contained in a variable. Named blocks can be restored later in 
any unit. 

The local keyword saves the flow settings in a memory pool block specific to the current 
20 unit A local block can be restored only in the unit which saved it; it is deleted automatically when 

execution of the unit ends. 

Saving the active flow settings to the default buffer makes them the default flow settings 
for all new main units. They are automatically reset on a jump or jumpop to another unit. 

The memory pool is used by the commands: memory, image, window, status, area, 
25 flow, font and perm. Memory blocks are tagged as belonging to a specific command type at 
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creation and cannot be accessed by other commands using the memory pool; different commaniijs 
can use the same name for a memory block without conflict. 
Example 1 

Saves the active flow settings under the name flows in the memory pool. 

5 flow save ; • flows ' 

Example 2 

Saves and restores the active flow settings over a subroutine call in a block unique to the 
unit. The block is automatically deleted when the unit is exited. 

flow save; local 

1 0 do routines , graph 

flow restore; local 

Example 3 

Makes the active flow settings the defaults for all subsequent units that are entered by a 
jump or jumpop branch. 

15 flow save; default 

flow restore; *NAME' | local [; delete ] 
flow restore; default 

Replaces the active flow settings with a previously saved set. Optionally, the named or 
local block can be deleted from the memory pool by using the delete modifier. 
20 Example 1 

Saves and restores the active flow settings over a library call. The library routine can alter 
the active flow settings as desired without affecting the calling program upon return. Alternately, 
the flow save and restore could be built into the library routine to provide a more easily used 
tool. 

25 flow save; 'flows' 
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library routines , graph ^ 
flow restore; 'flows' 

Example 2 

Re-activates the flow settings whose name is contained in the variable seiUp. The memory 
5 block is then deleted. 

flow restore; setUp; delete 

now delete; »NAME' 1 local 

Deletes a saved set of flow settings from the memory pool. 

Example 

1 0 Deletes the quiz set of saved flow events from the memory pool 

flow delete; 'quiz' 

flow reset 

Deletes all named sets of flow settings from the memory pool. The default set of flow 
settings are unaffected. 
15 now dir; keyBuffer [length] 

Lists the keys for all the active flow events. The key inputs are returned as a sequence of 
2-byte values (zero terminated if possible) into keyBuffer^ These values can be used as input for 
now info to obtain the full information about a flow event. The system variable znowcnt holds 
the number of active now events. 
20 Example 

Obtain the input key values for all the active flow settings. The inputs are returned as 2- 
byte values in a 50-element (maximum) array called value. 

define local 
value (50) ,2 
25 define end 
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flow dir; valued), zflowcnt •2 $$ read active flow keys 

now info; K£V: infoBufter l,length ] 

Returns the flow setting parameters for a specified key input value in the given buffer. 
5 The maximum length of information returned is 22 bytes. The optional length argument can limit 



the number of bytes returned. An extensive coding example using (low info is found in lesson 
TCSAMPLE unit i/flow. 



parameter 


bvte(s) 


values 


branch type 


1 


0= not flow event 
1 = jump 
2= jumpop 
3= do/library 


lesson 


8 


branch lesson name 


unit 


8 


branch unit name 


range 


1 


0= current mam unit only 

1 = default event for new main units 

2 = router (permanent event) 


active 


1 


0 = at normal wait states 

1 = complete (at end-of-unit) 

2 = break (interrupt processing) 


execution mode 


1 


-2 = no change on branch 
-1=10 binar\' 

0 = to source 

1 = to tor 


window 


1 


0 = no change on branch 

1 = window close 

2 = window reset 


base 


1 


-1 = set =base on branch 
0 = no change 



System Default Flow Settings 

While running your lesson, [SHIFT][F1],[F2] and [SHIFT][F2] are pre-defmed by the 
10 'authoring system as: 



flow jump; %F1; =exit; break; router 



SUBSTITUTE SHEET (RULE 26) 
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flow jun5>; ^FZ; =editor; break; router ^ 

flow juit5>; %f2; =system/ break; router 

Only [SHIFT][F1] is pre-defined by the student system as: 

flow jun5>; %F1 ; =exit; break; router 

5 These flow settings may be redefined, or deleted using flow clear with the router 

modifier. However, be sure to provide an alternate means to exit your lessons; otherwise a user 
could become stuck with no exit even to DOS. 

To temporarily save, clear and restore both the active and default flow settings over or 
within a library call, do the following: 

10 flow save; 'currents' $$ save active flow settings 

flow restore ;default $$ restore defaults to active 

flow save ;'def save' $$ save default flow settings 

flow clear ;;default 5$ delete all but router settings 

15 library routines , stuff $$ all settings but router can be changed 

flow restore; 'def save' $$ read back saved default settings 

flow save;default $$ set them back as defaults 

flow restore; 'currents' $$ restore saved active settings 

20 System Variables 

zreturn 

The save, restore, reset and delete forms of the flow command, which use the memory 
pool, report on success or failure in zreturn. All other forms set zreturn to ok (-1). The major 
zreturn values are: 
25 " - 1 Operation successfiil 

10 Name not found 
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1 8 Unable to fill memory pool request 

Miscellaneous 
zflowcnt Number of active flow settings 

zmaxflow Maximum number of flow settings allowed 

5 font 

Selects fonts for text display. 

font [ lESSON',] TONT[\ fontNumber I standard [jnoload ] ] 

font [ TESSON\] TONTGROUP' [; fontNumber I standard [;noload ] ] 

font ; fontNumber 

10 font standard [; standard ] 

font info; infoBuffer [Jength ] 

Description 

A font is a named block in a lesson. It contains character designs corresponding to some 
or all of the ASCII character codes 0 to 255. A font group is also a named block in a lesson. It 

1 5 contains a list of related fonts with different text attributes. 

The text command attributes of size, bold, italic and narrow interact with fonts and font 
groups. For a font, the appearance of the attributes is synthesized (except for narrow). When a 
font group is active, the system automatically selects the member font most appropriate for the 
text attributes enabled at any given time. 

20 One font or font group is always designated as the standard. The standard font is the 

basis for character screen coordinates, even if some other font is currently selected for text 
display. For example, at 5:10 specifies a screen position 5 standard character heights below the 
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top, and 9 character widths from the left. A font group appropriate for the current screen ^ 
resolution is automatically designated as the standard when an initial or screen command is 
executed. However, this standard may be overridden with a different font or font group, thus 
altering the character grid. 
5 A font or font group can optionally be associated with a reference number. This number 

alone can later be used to reselect the font. 

The status command saves and restores all font and text parameters: the selected font or 
font group, the standard font, the font number table, and text attributes. A status save;default 
statement is required to save these parameters over a jump branch to a unit. 
10 Fonts and font groups are kept in the memory pool. There is no need to explicitly delete 

fonts from memory; when space is required for other memory pool objects, they are automatically 
deleted and reloaded from disk if needed again. 

The system standard font groups exist in lesson TCSTDFNT. An additional set of 
decorative font groups is supplied in lesson TCFONTS. The Font Editor can be used to modify 
15 any of the fonts in these lessons, import fonts from other sources, or create custom fonts from 
scratch. 

font ['LESSONM TONT 

Selects a specific font from the current lesson or optionally from a named lesson. The font 
is brought from the disk to the memory pool and remains active until replaced by another font 
20 command or a jump branch to a unit which resets to the default font. 
Example 1 

The initial command causes all plotting parameters to be set to their system standard 
defaults including the standard font for the current screen resolution. Font gothic in the current 
lesson is then loaded and used for the following write text. Text attributes are then changed so 
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that the last write statement appears in a synthesized form of font gothic. The zreturn check 
indicates any system errors in loading the font from the disk. A zreturn check is recommended 
after any font command, but is omitted in the following examples to save space. 

initial 

5 write This text uses the system standard font, 
font 'gothic' 
if zreturn > -1 

write Error «s , 2return» loading Gothic 

endif 

10 write This writing uses character designs in font Gothic, 

text size; 2 

text bold; on 

write This writing uses a bold and dotible size font 

synthesized from font Gothic. 

15 Example 2 

Selects font buN8 from the decorative font library in lesson TCFONTS. This is the 48 
dot high version of burlesk. 

font ' tcf onts ' , »bur48 ' 

write This text is using Burlesk character definitions. 

20 Example 3 

Selects the font named in the variable fontVar from the lesson named in the variable 

fontLib 

font fontLib, fontVar 

font ('LESSONM TONTGROUP' 
25 ' Activates a font group and selects a font from the group based upon current text 

attributes. Specific fonts can exist in a font group for all 72 combinations of the text attributes 
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size (1 through 9), italic, bold, and narrow. The text command (along with its embedded an^. 

uncover code forms) sets these attributes and therefore determines which font is selected from the 

group. If a font with the required attributes is not found in the group, the closest match is used, 

and the nonmatching attributes are synthesized if possible. Attributes that can be synthesized are 
5 size (only 2 through 4), italic, and bold. The system variables zfontret and zfontf (see System 

Variables later) indicate how closely the current font selection from the group matches the text 

attributes currently in effect. 

By looking at a font statement, it is not possible to tell whether a font or font group is 

referenced. However, the block's type is displayed on the Block Directory page. 
10 Example 1 

The font group mine has 4 fonts in it specifically designed for size 1 and 2 in both normal 
and italic but not bold. Text attribute uncover codes in the write statements select for italic and 
bold. The italic comes from one of the designed fonts in the group while the bold is synthesized. 

font 'ztiine* 
15 text size; 1 

write This normal and ita^lic tsxt comes directly from 

specifically designed fonts but bold is synthesized, 
text size; 2 

write This size 2 normal and italic text comes directly from designed 
20 fonts while bold is synthesized starting from the size 2 normal 

and italic fonts. 

Example 2 

The size attribute causes the size 2 font to be chosen from each of the decorative font 

groups. 

25 text size; 2 
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font ' tcf onts ' , 'burlesk ' 

write This writing uses the font group burlesk. 
font ' tcf onts ' , ' opera ' 

write This writing uses the font group opera. 

5 font standard 

Selects the standard font or font group. This is one of the system standard fonts found in 
lesson TCSTDFNT, unless the standard font has been overridden as described in the following 
section. 

Example 

10 font 'gothic' 

write This text is in Gothic 

font standard 

write while this is in standard. 

font ['LESSONM TONT ; standard 
15 font [XESSONM TONTGROUF ; standard 

The optional keyword standard on a font selection causes the named font or font group 
to become the new standard, overriding the system standard font group. Any subsequent font 
standard statements select this new standard font or font group until a jump branch. 

To make the new standard font selection permanent for an entire lesson, use status 
20 save; default to make the selection part of the default display parameters that are restored upon a 
jump branch. Then, only a subsequent initial, screen, status restore;standard, or font 
standard;standard statement restores the system standard font group in lesson TCSTDFNT. 

System variables zcharw and zcharh report the width and height of the standard font at 
size 1 , These values are the basis for character screen coordinates. 
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Example — 
Variable typeface contains the name of the font to activate; it becomes the standard font. 
If the font is 32 pixels high and 32 pixels wide, then both the system variables zcharh and 
zchanv become 32. For screen vga,medium (480 pixels high and 640 pixels wide), the character 
coordinate grid now has 15 (480/32) lines and 20 (640/32) columns. The text for the write 
statement would appear at the graphic coordinates of x = 128 ((5-l)*32) and y = 416 (480- 
(2*32)). This character grid remains in force until the standard font is replaced. 

screen vga, medium 

font typeface; standard 

at 2:5 

write Character position 5 on line 2. 

font standard ; standard 

Restores the system standard fom group from lesson TCSTDFNT. This might be 
desirable if the standard font has been overridden earlier. 

The lesson TCSTDFNT contains the system standard font groups and fonts, one named 
for each venical screen resolution: the names begin with the letters std followed by the vertical 
resolution of the screen. For example, std350 is for ega,medium screens, std480 for 
vga,medium screens, and std600 for vga.high screens. Whenever a font standard;standard 
or initial, screen, or status restore;standard statement is executed, the current screen 
resolution is used to select the system standard font group. Since it is a font group, the font 
selected from the group depends upon the current text attributes. 

The system standard fonts can be changed by editing the fonts and font groups in lesson 
TCSTDFNT and then making a new binary to replace TCSTDFNT.BIN. 
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font ('LESSON',] 'FONT' fontNumber I;noload ) 

font [XESSONM TONTGROUP* ; fontNumber {;noIoad ) 

Selects a font or font group and assigns it a unique number from 1 to 35. Numbered fonts 
can be accessed by an uncover code sequence embedded in text This allows switching between 
5 fonts within a single write command, for example. 

In the Source Editor, entering the sequence [CTRL][A],[F],[1] - [9] enters the uncover 
codes for the first 9 numbered fonts while the sequence [CTRL][A],[F],[A] - [Z] enters the codes 
for the numbered fonts 10 through 35, In student mode at an arrow, a similar sequence of codes 
can be used for switching fonts but the default uncover code sequence starts differently: 
10 [CTRL][U],[M],[F],[A]-[z]. 

Numbered font statements can be included in the +editor control block of a lesson so that 
text with embedded font selection sequences appears in the correct fonts during editing. 

Font number assignments are saved and restored by the status command. 

A single font or font group may be assigned more than one number by using multiple font 
15 commands. If this is done, any of the numbers assigned to the font can be used to select it. 

However, a given number can be associated with only one font or font group at a time. The most 
recent assignment of a given font number overrides any earher assignment. 

The optional keyword noload is used to allow a font or fontgroup to have a font number 
association without actually loading the font into memory. This option can save disk read time at 
20 the start of a routine where muhiple fonts need to be associated with font numbers. Later, the 
font will be automatically loaded as needed when referenced by its number embedded in write 
statements. 
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Example 1 ^ 
Two numbered fonts are loaded. Uncover code sequences are used to switch between 
fonts within the text of the write statement. (Uncover code sequences become visible when 
display of hidden characters is turned on in the Source Editor.) 
5 font 'gothiC ; 2 

font 'geneva' ; 3 

write This text is Geneva, -fS switches to Gothic, then .-f2 back to 
Geneva . 

Example 2 

10 In the ^initial control block, the three numbered fonts are put into the default display 

status buffer. Any jump branch to a unit resets to these three numbered fonts so that they can be 
used through uncover codes in text of write, pack, etc. statements. If the font statemems are 
also put into the -.editor control block, any text with the font uncover codes (such as the write 
statement of this example) would be displayed in its chosen font durmg editing. The optional 

1 5 keyword noload is used to avoid any possible startup delays. 

in the +initial control block 



; noload 

tcfonts',' poster*; 2 ; noload 

xrdne*,' firework'; 3 ; noload 



font * tcf onts ' , ' geneva ' ; 1 

font 
font 

20 status save; default 



in units throughout the lesson 
write afl Geneva, mtZ Poster, -fS Fireworks 

font ;fontNumber 

Selects a font or font group that was previously assigned a number. 
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Example 

Two numbered fonts are loaded. Several write statements switch between using the two 
fonts by referencing their numbers alone. 

font 'gothic' ; 2 

5 font • geneva ' ; 3 

write This text is Geneva then 

font ;2 

write switches to Gothic then 

font ;3 

10 write back to Geneva. 

font info; infoBufTer [^length) 

Reads information about the selected font or font group into a buffer for the given length 
in bytes. If the length is not specified, the defined length of the buffer is used. 
The following 256 bytes of information are available: 



System Data (100 bvtes) 


Bvtes 


1 OfTset 


font lesson name 


8 


0 


font block name 


8 


8 


font group lesson name 


8 


16 


(font lesson if font loaded) 






font group block name 


8 


24 


(font block if font loaded) 






font number (-1 =standard, 0=unnumberd) 


1 


32 


font group (-I=yes, 0=no) 


1 


33 


character width 


2 


34 


character height 


2 


36 


baseline offset 


2 


38 


underline offset 


2 


40 


underline thickness 


2 


42 


underline gap 


2 


44 


shadow X offset 


2 


46 


shadow V offset 


2 


48 


italic angle (real) 


4 


50 


spacing decrement (0=no, l=ves) 


1 . 


54 


(reserved) 


45 


55 
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Descriptive Information (156 bytes) 


Bytes 


Offset 


font name 


16 


100 


revision number 


1 


116 


family 


1 


117 


subclass 


1 


118 


style 


1 


119 


weight 


2 


120 


points 


2 


122 


horizontal resolution 


2 


124 


vertical resolution 


2 


126 


(reserved) 


48 


128 


copyrieht 


80 


1 176 



Example 

The copyright message for the standard font is displayed. 

define local 

5 infobuf,256 

17g $$ skip other fields 

copyrt,80 $$ copyright field 

define end 

10 font standard 

font info ; inf obuf 

at 10:1 

showa copyrt,80 

System Variables 
15 zreturn 

After a font command, zreturn indicates the success of loading a font: 
. 1 Operation successful 

0 Disk error (see zdoserr, zedoserr) 

2 No font in group 
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4 File not found 

1 0 Font name not found 

1 5 File directory error - unrecoverable 

18 Unable to fill memory pool request 
5 zfontret 



The system variable zfontret indicates how closely the current font matches the text 
attributes currently in effect, 
zfontret for a font; 



-1 Font loaded successfully 

10 2 Unable to load font; standard font used 

3 Unable to load standard font; charsets used 
zfontret for a font group (and updated when text attributes change); 

-2 Exact match of attributes; some synthesis used 

- 1 Exact match of attributes 

1 5 0 Partial match of attributes 

1 No suitable match; base font used 

2 Unable to load base font; standard font used 

3 Unable to load standard font; charsets used 
zfontf 



20 For font groups only, zfontf contains a bit field that reports on how the attributes are 

produced whenever a font is loaded or text attributes change causing the selection of another font 
in the group. 

zfonffbit meaning 

6 Bold matched in font group 
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7 Italic matched in font group ^ 

8 Size matched in font group 

16 Narrow matched in font group 

22 Bold synthesized 

5 23 Italic synthesized 

24 Size synthesized 

The attribute may not match the request but also may not be synthesized; for example, if 
the font group only has bolded items, and the current attributes specify non-bolded, then bits 6 
and 22 will both be off 
10 Miscellaneous 

The following system variables are set after loading a font and are updated if appropriate 
when text attributes change: 

zfonth Character height and width of selected font 

zfontw 

15 zcharh Character height and width of standard size 1 font 

zcharw (basis for the character coordinate system) 

zfontb Baseline offset of selected font 

zcharb Baseline offset of standard size 1 font 

goto 

20 Transfers execution to another unit or to the end of unit, 
goto UNIT\<\ 

goto SELECTOR- UNIT 1 q; UNIT 1 q ; . . . 
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Description ^ 

.AJlows the logical continuation of the current unit into another unit, goto switches 
execution to the specified unit but does not: erase the screen, clear the do return markers, change 
the main unit, or alter a help sequence. 
5 The q keyword transfers execution to the end of the unit. 

The goto command is considered by many as an obsolete programming method properly 
replaced by structured programming, 

if 

Begins an if structure. 

10 if condition 
Description 

Marks the beginning of an if structure. If the condition is true, any following indented 
code is executed. If the condition is false, execution continues with the next non-indented elseif, 
else, or endif. 

15 .\n if structure is the main conditional structure in the TenCORE language. The 

commands which make up an if structure are: 
if 

elseif (optional, any number) 
else (optional) 
20 endif 

The if structure begins with an if and ends with an endif. Commands to be executed when 
a particular condition is true are indented immediately following the if, elseif, or else. Indenting in 
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TenCORE consists of a period in the first character of the command field followed by 7 spaces^ 
(one tab stop in the source code editor). The command and tag of the indented command are then 
typed as usual. 

In any if structure, only one set of indented commands is executed. The condition is 
5 checked on each if and elseif in succession. The indented commands beneath the first if or elseif 
that is true are executed and then control passes to the command after the endif. if none of the 
conditions on if and elseif are tme, the indented commands following any else are executed. 
Examples 
Example 1 

10 If the value of the variable score is over 75, the indented commands are executed. 

if score > 75 

do goodfb 
jump endless 

endif 

15 Example! 

elseif and else commands are used in an if structure. 

if right = 0 $$ user missed all questions 

do verybad 

jump helppg 

20 elseif right < 5 $$ user got 1 to 4 right 

do notgood 

jump quiz 

elseif right < 10 $$ -user got 5 to 9 right 

do good 

25 . ' jump review 

^^^^ $$ user got more than 9 right 



3NSDOCI0 <WO 9907007 A2. 1 > 



wo 99/07007 PCT/US98/15627 

275 

do great 
jun^ endless 

endif 

Example 3 

5 An if staicture is nested. 

if wrong > 5 $$ user missed more than 5 

write You are making too many mistakes! 

pause 

if wrong > 10 $$ user missed more than 10 

10 . . jump quit 

endif 

endif 



image 

Displays, captures and manages screen images. 



1 5 image keyword 




plot 


displays the specified image 


save 


captures all or part of the screen to the specified destination 


move 


transfers an image between storage areas 


info 


returns information about an image 


20 delete 


deletes the specified image from the memory pool 


reset 


deletes all images from the memory pool 


compress 


turns compression of image data on or off 


palette 


reads palette information from an image 
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Description — 
The image command is used to plot completed pictures onto the display, to capture 
pictures off the display or to move pictures between variables, memory pool blocks and disk 
storage locations (namesets, datasets, and lessons). Pictures are screen images that are: created in 
5 image blocks by the Image Editor imported into image blocks from existing bit-map images 
created by "paintbrush" programs or a part of a screen that is directly captured and saved by 
either the Image Option -after pressing System Key [F2] or executing an image save command, 
image plot; from [ ;[ LOCATION] [ ;palette ] ] 

Plots the specified image at the same location it was saved from, unless a location is 
10 specified. In either case, the current screen location is not changed. The display mode as set by 
the mode command is used in plotting the image. (See mode for additional information.) if the 
keyword palette is specified, the palette stored with the image is used. If palette is not specified, 
the palette is not changed. Images plot downwards from the specified location, which 
corresponds to the upper left corner of the image. 
15 /rom keywords and syntax: 

block I h,'NAME' 

Plots an image block from the specified lesson. If only the image name is specified, 
the current lesson is assumed, 
file I f { .record ] 

20 Plots from the attached dataset or nameset, starting at record 1 unless a starting 

record number is specified. In the case of a nameset, a valid name must have been previously 
selected with the setname command. 
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10 



memory | m ,'NAME' ^ 

Plots from a memory pool block. The name may be a literal in single quotes, or occur 
in a variable. 

vars I V ,variable ( ,length J 

Plots from variables. The defined length of the variable is used unless a length is 
specified. 
Examples 

image plot;block, ' horse 20 , 100 

* block "horse" at location 20,100 

image plot;block, ' library horse ' 

* block "horse" in file "library" 



image plot; file 
15 * currently attached file 



20 



image 



a.mage 



plot; memo ry , my image 

name contained in the variable myimag-e from memory pool 

plot; vars , picsave 

image in variable "picsave" 



image plot; memory, 'show' ; 15 : 01 ;palette 

* plot using the palette stored with the image 

image save; destination [; [LOCATION] ; [LOCATION]! ; palette [,variable]|l 

25 ^ Saves the area of the screen specified by the rectangular area to destination. If no display 
area is specified, the entire screen is saved. If the palette keyword is used, the current palette is 
stored with the image as well. If variable is give~n, only those colors specified in variable are 
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saved with the image. See palette read for the format of variable. The image is saved in a special 
compressed format in order to use as little storage as possible. 
destination keywords and syntax: 
file I f [ ,record ] 

5 Saves to the attached dataset or nameset, starting at record 1 unless a starting record 

number is specified. In the case of a nameset, a valid name must have been previously selected 
with the setname command. The number of records required to save an image can be calculated 
as: (bytes + 255; SidivS 256. 
memory 1 m /NAME 

10 Saves to a block in the memory pool. The name may be a literal in single quotes, or occur 

in a variable. If an image is already stored with the specified name it is replaced. Names in the 
memory pool created by image are independent of any names created with other commands. For 
instance, the memory command and the image command can both create a name in the memory 
pool called cat without causing a conflict. The initial command deletes all images from the 
1 5 memory pool. 

vars ! v ,variable [ ,length ] 

Saves to variables. The defined length of the variable is used unless a length is specified. 
The image may be truncated if the defined length of variable is insufficient 
Examples 

20 define local 
palblock(16) ,6 

palslot ,2 
define end 
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image save ; file ; 50 , 20 ; 150 , 80 
* save in attached file 



image save;memory, 'pic' ; 0,0; 99, 99 
5 *save in "pic" , memory pool 

image save;memory, 'save' ; 0", 0 ; zxmax , zyitiax; palette ,palblock (1) ,10 

* save the first ten entries of the palette 

image move; from; destination 

10 Copies an image between a from and a destination when neither is the screen. 

Example 

image move ;block , ' abc ' /memory , ' def * 

* from "abc* in current file to block "def" in memory pool 

block cannot be used for destination, since that would modify a running lesson source 
15 file. Also, if destination is file, then from can only be memory or vars. 
image info; buffer; from | last [; palette] 

image info;bufter; display 1 d, LOCATION [; [LOCATION] [;palette]] 

Returns information about an image specified by from. The information is returned as 24 
bytes in the specified buffer in the following fixed format: 
20 1 byte: image type 

0 = byte-oriented (CGA, EVGA etc.) 

1 = plane-oriented (EGA VGA, etc.) 

2 = text image 

1 byte; bits per pixel (byte-oriented) or number of planes 
25 2 bytes: bias from left of screen 
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2 bytes: bias from top of screen ^ 
2 bytes: image width 
2 bytes: image height 
4 bytes: number of bytes used by image block 
5 10 bytes reserved 

Bias, width, and height are given in pixels for byte- and plane-oriented images, and in 

character positions for text images. 

Adding the palette keyword causes palette information to be included in the returned 

length of the image. 
10 Additional /rom keywords and syntax exits for image info: 

display I A,LOCATION[\[LOCATION] [ ; palette H 

The image is taken directly from the screen. This form can be used to determine how 
much space a particular image on the screen will require, before creating a file to hold the image, 
last [;paiette 1 

15 The last image processed by the image command. 

Example 

define local 
inf ovar , 2 4 

type,l 
20 . bits,l 

xstart,2 
ystart,2 
xsize ,2 
ysize ,2 
25 . length , 4 
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,10^ 

define end 

image inf o ;infovar /display ,50 ,50 ; 100 , 100 
5 at 2:1 

write Image will require «s,length» bytes for storage 
pause passs all 

created ' imagel ' , {length+255) $idiv$ 256 

do zre turn;; err or ('created') $$ always check zreturn 

10 image save ; file ; 50 , 50 ; 100 , 100 

image delete; 'iNAME' 

Deletes the specified image from the memory pool, 
image reset 

Deletes all images from the memory pool. 
15 image compress; ( on | off ] 

Toggle image compression. Compressed images occupy less memory or disk space; non- 
compressed images in memory plot faster The default is on. 
image palette; from ; buffer, entries 

Reads image palette entries into a buffer. The buffer must contain one or more 6-byte 
20 palette entries in the form of 

slot (2bytes) 
red (1 byte) 

green (1 byte) 

blue (I byte) 

25 intensity (1 byte) 
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The value of slot must be pre-set for each palette entry before executing image palette. 
The value of each slot will determine which palette slot's information is read into that entry. For 
example, if the value of slot for a particular entry is 8, the information for palette slot 8 will be 
read into that entry. If the values of slot are not set, slot 0 will be read into all the entries. Any 
5 subset of palette entries may be read or written by setting appropriate slot values. 
entries determines how many entries will be read. 
Example 

Reads the palette information for the base 16 palette entries from the image in memory 



15 



block test: 




define 


local 


pvar (16) 


,6 




slot, 2 




pred, 1 




pgreen, 1 




pblue , 1 




intensty, 1 


count 


,2 


define 


end 


* 




loop 


count c= 1 



*must initialize slot nuinbers 

calc slot (count) <:= count - 1 

endloop 

25 image palette; memory, ' test ' ;pvar (1) , 16 
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Screen Compatibility 

To be able to display an image from one screen on another screen, they must be of the 
same type. There are three types of image: 

• graphics byte-oriented, such as the CGA, Hercules, MCGA, and EVGA 
5 • graphics plane-oriented, such as the EGA, and VGA 

• text 

For graphics screens, the number of bits per pixel (byte-oriented) or number of planes 
(plane-oriented) must also be identical. Text images are compatible among all text screen types. 
The characteristics of a given image can be determined using the image info command. 
10 The following tables list the characteristics of the graphics screens currently supported by 
TenCORE: 



Bvte-oriented Screens 


Bits/pixel 


cga,medium 


2 


cga,high 


1 


hercules 


1 


mega, high 


1 


mcga,medium 


8 


evea 


8 




Plane oriented Screens 


Number Of Planes 


ega 


4 


vga 


4 



For example, in the byte-oriented group, the cga high, hercules, and mega high images are 
compatible with each other. In the plane-oriented group, all listed screens are compatible with 
1 5 " each other. Caution: even though an image from one screen is compatible with another screen, 
it may look different on the other screen due to changes in aspect ratio. For example, an ega 
high image plotted on a vga medium screen will be the same width, but only be about 73% of the 
original height. 
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System Variable ^ 
zreturn 

_l Operation successful 

0 Disk error (see zdoserr, zedoserr) 

5 I No file attached 

2 Block out of range 

3 Memory out of range 

4 File not found 

5 Image screen type doesn't match execution screen type 
10 8 Insufficient disk records 

9 No name in effect 

1 0 Name or block not found 

1 1 Invalid type 
16 Invalid name 

15 17 Invalid image 

1 8 Unable to fill memory pool request 



initial 

Initializes the system to a standard state, 
initial [ nodetach ] 

20 Description 

Sets the system to a standard state. It is normally used when starting a lesson, as in a 
+initial control block, to set all system parameters to a known state. 
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The nodetach keyword prevents the currently attached file from being detached, and ^ 
preserv-es any locks which are in effect for shared files. 

The initial command performs the following command initializations: 



Display 




wmdow 


reset; noplot 


status 


restore; standard, 


blink 


off 


color 


white 


colore 


black 


colorg 


black 


disable 


cursor 


enable 


font 


font 


standard; standard 


mode 


write 


origin 


0,0 


rotate 


0 


scale 


1,1 


text 


align; baseline 


text 


bold; off 


status 


save; default 


palette 


init 


disable 


absolute 


text 


delay; 0 


text 


direction; right 
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10 



15 



20 
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text 

text 

text 

text 

text 

text 

text 

text 

text 

text 

thick 

page 

display 

Input 

disable 

disable 

enable 

area 

area 

uncover 

force 

time 

Branching 

flow 
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increment; 0,0 
italic; off 
margin; wrap 
narrow; off 
reveal; off 
rotate; 0 

shadow; off, white 
size; 1 

spacing; fixed 
underline; off,foregnd 
off 
1 



pointer 

ptrup 

area 

clear; default 
highlight; off 
%ctl"u" 
no lock 

clear $$ all but router 



clear;default 
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enable break 

base 

Disk 

disk - 1 $$ search all drives for files 

5 edisk -1 

detach ail 

nsdirwr -1 S$ always write nameset directory 

Judging 

enable arrow 

10 okword 'ok' 

no word 'no* 
General 

memory reset SS all but router 

status reset 

1 5 area reset 

flow reset SS all but router 

perm reset 

image reset 

version SS no version emulation 

20 Videodisc Overlay 

video init 

video unitinit, on 
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intcall 

Calls a software interrupt. 

intcall number, pass, receive [ ;extended ] 
number interrupt routine to call 
5 pass data passed to the interrupt routine (8 or 20 bytes) 

receive data returned from the interrupt routine ( 8 or 20 bytes) 
extended forces the use of extended registers 

Description 

Calls the interrupt specified by number. In the non-extended form, the registers AX, BX, 
10 CX, and DX are set to contain the four 2-byte values from pass. Registers DS and ES are set to 
point to the global or local variables segment as appropriate for xh^pass variable; SI and DI are 
set to the offset within the segment. On exit from the routine, receive contains the four 2-byte 
values residing in the AX,BX,CX and DX registers, zreturn contains the low byte of the FLAGS 
register, 

1 5 The extended keyword forces the use of the extended set of registers allocated to the 20 

byte pass and receive variables in the following order: 

AX,BX,CX,DX,SI,DI,BP,DS,ES,FLAGS 

Addresses 

The following system-defined function references are sometimes useful in setting or 
20 interpreting registers used with intcall: 

sysloc(global) Segment address of global variables 

sysloc(local) Segment address of the current unit's local variables 
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varloc(var) Offset address of the variable var ^ 
absloc(var) Absolute location of var within memory, expressed as a 4-byte offset 
with no segment. Corresponds to the segment:offset address as follows: 
segment = abslocQ SarsS 4 
5 offset = absIocQ SmaskS hOf 

absloc = ((segment SmaskS hOOOOfiff) Scls4S 4) + (offset SmaskS hOOOOfffi) 
Example 

Executes interrupt hi 2, which returns the memory size. The interrupt requires no input 
data, so the same variables are used for input and output. 
10 define local 
regstrs , 8 

ax, 2 $$AX data 

bx, 2 $$BX data 

cx, 2 $$CX data 

15 . dx, 2 $$DX data 

define end 

* call bios interrupt hl2 , "memory size determine" no input 

* parameters, so the same variables can be used for 

* input and output 
20 * 

intcall hl2 , regstrs , regstrs 
at 5:5 

write You have «s , ax $imul$ 1024» bytes of memory. 
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System Variable ^ 
zreturn contains the lower byte of the computer's internal flags register. The function 
reference bit(zreturn,8) can be used to test the carry (CY) bit, often set by software interrupts to 
indicate an error condition. See intcall online documentation for FLAGS register definition. 

5 jump 

Branches to a new main unit, 
jump UNIT [ (argument/16s) ] 

jump SELECTOR; UNITl ('argument 16s) ]; UNIT[ (argument 1 16s) ];... 
jumpop UNIT[ (argumen/ /16s) ] 
10 jumpop SELECTOR; W\7r [ (argument'! 6s) ]; UNIT[ (argument/'l 6s) ];.,. 

Description 

The jump and jumpop commands branch to the specified unit making it the new main 
unit. Optionally, up to 16 arguments may be passed to the new main unit. All flow branch settings 
are cleared (except for router settings) and restored to their defaults. 
15 A jump branch restores all plotting parameters to their default values (see status) and 

erases the screen (or window) to the colore color. All pointer areas are cleared and restored to 
their defaults. 

A jumpop (jump on-page) branch does not change plotting parameters, area settings or 
perform a screen erase. 

20 The flow command with jump keywords performs similar functions. However, flow is a 

delayed event-driven branch while jump occurs immediately when the command is executed, 
jump also allows arguments while flow does not. 
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The SELECTOR form is described in the "Syntax Conventions", jump has an additional 
q (for quit) list entry form that if selected terminates further execution of the current unit. See 
Example 4. 

' Up to 16 arguments, separated by commas, can be passed with the branch. These are 

5. evaluated with the execution of the jump and their values are passed to next unit. A receive 
command in the next unit is used to accept the arguments. See the receive command for further 
information on argument passing and the system variables zargs and zargsin that are set when 
passing arguments. 
Examples 
10 Example 1 

juirp two 

Branches immediately to unit nvo in the current lesson. The screen is erased and all 
defaults are re-established. 
Example 2 

15 jump rivers , «naiTve» 

Branches to the unit specified by variable name in lesson rivers. 
Example 3 

jurrpop build (98.6, men+women, size) 
20 receive temp, total, size $$ in unit build 

Branches (without a screen erase) to unit buiid in the current lesson passing as arguments: 
the constant 98.6, the evaluation of the expression r?7en^women, and the value in the variable 
size. In unit build, the receive statement accepts the passed arguments into variables. Since the 
screen is not erased with jumpop, unit build can add more to the existing screen display. 
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Example 4 ^ 
jump x-2; one; two; three; q 

This selective form of jump branches to unit one if .v-2 is negative, to Avo if 0, to three if 
1 and quits executing any further commands in the current unit for values greater than 1. 
Generic Unit Names 

Generic branch names are provided for common jump destinations to new main units: 
rznext The unit which physically follows the current main unit in the lesson. If 

none, the branch is ignored. 
The unit which physically precedes the current main unit in the lesson. If 
10 none, the branch is ignored. 

The first executable unit in the current lesson. 
The last executable unit in the current lesson. 
The current main lesson and unit as held in the system variables 
zmainl,zmainu. 

1 5 =base The main lesson and unit from which the last base modified flow branch 

occurred or as set by the base command. If none, the branch is 
ignored. The names of the current base lesson and unit are held in the 
system variables zbasei,zbaseu. Typically used for returning from a 
supplementary lesson sequence such as help to the main line of study. 
20 =editor The source editor (loaded with the current executing unit) if executed by 

the authoring system; ignored by the student executor. 
The lesson exit as set by the exitles command and contained in the system 
variables zexitl,zexitu. Student users are typically branched back to 
their routing system such as the TenCORE Activity Manager or DOS 



=back 

=first 
=Iast 
=main 

=base 



=exit 
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if none is present. An author testing a lesson is returned to the File 
Directory. 

=system Opens the system options window with the calculator, image capture, 

cursor, etc. [F2] is normally loaded with this branch as a TenCORE 
5 system default during authoring; ignored by the student executor. 

Example 

A learner proceeds to the next main unit if the question is answered correctly on the first 
try. If two or three tries are required, the current main unit is redone. For any other number of 
tries, the base unit pointer is set and the student is branched to a helping unit called trouble. In 
10 unit trouble, a jump to =base would return the learner to the base unit for another try at the 

question. This code would work equally well as part of the main unit or as a subroutine called by 
all the questions in the lesson, 
if tries - 1 

junp =next $$ go on to next question 

15 elseif tries < 4 

jump =main $$ re-do this unit 

else 

base «2inainu» $$ set base to current main unit 

jxin^s trouble $$ give learner extended help 

20 endif 

library 

Does a subroutine call to a binary unit. 

library UNIT[ ( [ argument/16s ][ ; retum/16s ] ) ] 

library SELECTOR; UNIT[ ( [ argument/16s ][ ; return/16s ] ) ];... 
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Description ^ 

A special form of the do command (which see) that does a subroutine call to an external 
binary library regardless of whether the calling unit is being executed in source or binary mode. 
The format is identical to do including the passing of arguments to and from the called unit. This 
5 command is used for calling completed routines or third-party TenCORE software that exits only 
in binary form. When a binary is made of a lesson, library and do work identically. 

If the calling unit is executing in source mode (by running source code directly from the 
Source Code Editor), library switches to binary execution mode for the subroutine call. When 
returning from the called umi back to the calling un\x, source mode execution is resumed. If the 
10 called library routine jumps to a new main unit, execution continues in binary mode and the 
"return to editing" key [F2] no longer operates. 

See the operate command for a discussion of source and binary execution modes and 
how they can be explicitly controlled. 

loadiib 

15 Loads a binary unit into the unit buffer, 

loadiib UNIT 

loadiib SELECTOR; UNIT; UNIT; 
Description 

Loads a binary umt into the unit buffer cache for execution by a subsequent library 
20 command. The unit is fetched from a binary file regardless of the type (source or binary) of the 
invoking unit or the status set by operate. 
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loadlib can be used to check for the existence of a unit before executing it, or to force 
units into memory. This can be useful for speeding up following sections of code, or for allowing 
the diskette on which the units reside to be removed. 

; loadlib should be used with caution: any non-executing unit can be purged from memory 
5 if space is needed for the execution of a unit. 
Example 

Unit copyfile is pre-loaded from the binary copy of lesson libfile. Unit copyfile copies 
files from one diskette to another. Once loaded, the diskette containing lesson libfile can be 
removed. 

10 loadlib libfile, copyfile 

* force binary unit copyfile into memory 

juicp zreturn;; erroru $$ always check rreturn 

at 5:5 

write Now put the diskette to copy FROM in drive A and the diskette to 
15 copy TO in drive B. 

Press Enter to begin the copy 
pause pass — %enter 

library libfile, copyfile $$ guaranteed to be in memory 

System Variable 
20 zreturn 



-1 Operation Successful 

0 Disk error (see zdoserr, zedoserr) 

4 Lesson not found 

10 Unit not found 

25 1 1 Invalid type 
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16 Invalid name ^ 

21 Conflict with another user's lock 

loadu 

Loads a unit into the unit buffer. 

5 loadu UNIT 

loadu SELECTOR; UNIT; UNIT;.., 

Description 

Loads the specified unit from disk to the unit buffer cache without executing it. loadu can 
be used to load one or more units in advance to avoid later disk access delays, to check if a unit 
10 exists, or to load a unit from a diskette that is to be removed. 
Example 

Unit copy/lie is pre-loaded. Unit copyfile copies files from one diskette to another. Once 
loaded, the diskette containing the routine can be removed. 

loadu copyfile $$ force unit copyfile into memory 

15 jump zreturn;; erroru $$ always check zretum 

at 5:5 

write Now put the disk to copy FROM in drive A and the disk to copy 
TO in drive B. 

20 Press Enter to begin the copy, 

pause pass = %enter 

juirqp copyfile $$ guaranteed to be in memory 
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System Variable 
zreturn 

-1 Operation Successful 

0 Disk error (see zdoserr, zedoserr) 

5 4 Lesson not found 

10 Unit not found 

1 1 Invalid type 
16 Invalid name 

2 1 Conflict with another user's lock 

10 loop 

Starts a loop structure. 

[CONDITION] 
loop counter start, end [ , increment ] 

counter variable to serve as the index counter 
1 5 start staning value for counter 

end ending value for counter 

increment increment (decrement)for the index counter 

Description 

Begins a loop structure ended by endloop used to repeat a series of commands for a 
20 specified number of times or while a condition is true. A loop structure can contain reloop and 
outloop commands (which see) at the same level of indentation. All other commands must be 
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indented. Loops may be nested within each other, but the range of the inner loop must be whdly 
within the range of the outer loop. 

The assignment arrow (c:) distinguishes an ITERATIVE loop from a WHILE loop, 
loop [CONDITION] 

5. The code within the WHILE loop structure is executed for as long as the CONDITION is 

true. If no tag is given, repetition is continuous unless an exit is provided via outloop, jump, etc. 

If a condition is present, its value is tested each time execution returns to the loop 
command. If the condition is true, a new iteration is begun; if false, the loop exits. 
Example 

1 0 Plots a line of X's on the screen using a WHILE loop, 

at 5:1 

loop zspace < 80 $$ while zspace is less than 80 

write X 

endloop 

15 loop counter c= start, end [ ,increment J 

An ITERATIVE loop repeats for the number of times indicated by the controlling 
arguments, counter is assigned the value of siarL Each time execution returns to the start of the 
loop, increment is added to counter. If increment is omitted, the default value is 1. If increment is 
a negative, the value of counter will decrease. If counter has passed the value of end (in whatever 
20 direction the loop is counting), the loop terminates. 
Example 1 

loop index <:= 1,10 $$ loop from 1 to 10 

at index: 4 

write index is «s,index» 

25 endloop 
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Example 2 

A WHILE loop is used to limit the horizontal plotting on the screen. The ITERATIVE 
loop plots a random number of X's with each iteration of the WHILE loop. 

at 10:1 

loop zspace < 80 $$ while zspace is less than 80 

calc random c= randi(lO) 

loop index c= 1, random 

write X 

endloop 
10 . pause . 5 

endloop 

memory 

Manages memory pool data storage. 

memory keyword;.., 

15 create allocates new memory block 

read transfers data from memory block to variables 

write transfers data from variables to memory block 

exchange exchanges data between memory block and variables 

move transfers data between memory blocks 

20 delete deletes named memory block 

reset deletes all memory blocks 

rename changes name of memory block 

resize changes size of memory block 
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info returns block information in system variables 

total changes total size of memory pool 



Description 

Provides access to the memory pool. Memory in the pool is allocated by named blocks. 
5 Data in a variable (buffer) can be written and read from these named memory pool blocks. The 
system automatically manages the memory pool as blocks are created, deleted, and resized. The 
main memory pool consists of all unused DOS memory below 640 Kilobytes. Secondary(virtual) 
memory such as expanded(EMS), extended(XMS), and disk memory is used to expand the main 
memory pool. 

10 Most memory command calls should be followed by a zreturn check to verify successful 

performance. 

The initial command deletes all memory blocks. An execution error also deletes all 
blocks, and restores the size of the memory pool to the size at startup. 

The memory pool is used by the conamands: memory, image, window, status, area, 
1 5 now, font and perm. Memory blocks are tagged as belonging to a specific command type at 

creation and cannot be accessed by other commands using the memory pool. Different commands 
can use the same name for a memory block without conflict, 
memory create; 'NAME ',size [; fixed \ router | temporary ] 

Creates a named zero-filled block of the given size in the memory pool. When a block is 
20 allocated in the memory pool, its size is rounded up to a multiple of 16 bytes. In addition to its 
rounded-up length, each memory block uses an additional 16 bytes in the pool. 

The optional modifier fixed pins the block to a fixed place in memory whose address is 
found in the system variable zmstart. Fixed blocks should be avoided except where absolutely 
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required since they degrade the operation of the memory pool. An example use of a fixed block is 
as a communication buffer with an external program. 

Normally, a memory block is deleted by initial or memory reset unless the optional 
keyword router is present A router modified memory block can only be deleted with an explicit 
5 memory delete; 'NAME* or memory reset ; router statement, router modified memory blocks 
are accessible from any domain and are not deleted by the deletion of the domain in which they 
were created. 

A temporary modified memory block is deleted automatically when the system requires 
additional memory pool space: it is useful for holding data that can be regenerated when 
10 necessary. 

The modifiers are mutually exclusive: only one can occur in a memory create statement. 
Example 1 

Creates a 1000-byte memory block called temp in the memory pool. A jump to unit error 
occurs if an error such as insufficient memory occurs. 

1 5 memory create ; ' teirp ' , 1000 
jump zre turn ;; error 

Example 2 

Creates a 200-byte fixed memory block using the name contained in the 8-byte variable 

name, 

20 memory create; name ^ 200; fixed 
jump zreturn ;; error 

memory write; 'NAME SofTset; buffer; length 

Transfers data to the named memory block starting at the given offset from a variable 
buffer for the given length of bytes. All offsets in memory blocks start at 0: to reference the 
25 beginning of a memory block, use an oflFset of 0, 
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Example 

Transfers S bytes from variable score to memory block results, starting 32 bytes past the 
beginning (0) of block results. Jump to an error routine if something goes wrong. 

memory write; • results 32 ; score; 8 
5 jiamp zreturn; ; error 

memory read; 'NAME •,offset; buffer; length 

Transfers data from the named memory block starting at the given offset to a variable 
buffer for the given length of bytes. 
Example 1 

1 0 Transfers 256 bytes of data from the beginning (offset 0) of memory block info to the 

buffer infobuf. Jump to an error routine if something goes wrong- 
memory read; 'info',0; infobuf; 256 
jtut^) zreturn; ; error - 

Example 2 

15 All global variables are saved and restored over a call to a library subroutine. First, a 

memory block called sctveVars is created. The global variables are transferred to this memory 
pool block. A library routine is called that may change the global variables as desired. Finally, the 
global variables are restored. 

define global 

20 globals=29696 $$ assume default global space (29 Kilobytes) 

varBlock , globals , block 
define end 
* 

'memory create; ■ savevars globals $$ create globals block 

25 jump zreturn; ; error 

memory write; » savevars ' ,0; varBlock; globals $$ save globals 
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jump 



zreturn ; ; error 



zero 



varBlock , global s 



$$ perhaps zero all globals 



library routines , graph 



$$ can use all globals 



5 



memory read; ' savevars ' , 0 ; varBlock; globals $$restore globals 



juir^j 



zreturn; ; error 



memory exchange 'NAME ',ofTset; buffer; length 

Exchanges data between the named memory block starting at the given offset, and a 
10 variable buffer for the given length in bytes. 



memory exchange; block, 0; buf{i); 12 

Swaps 12 bytes of data between the start of the memory block named in block and the 
array buffer staning at bnf(i). 
15 memory move; TROiMNAME ',ofTset; TONAME \ofTset; length 
Moves data directly between memory blocks. 
Example 

memory move ; ' databuf * , 0 ; * backup ' , 3 ; 256 

Transfers 256 bytes of data from the beginning of memory block daiabuf to memory 
20 block backup starting at offset 3. 
memory delete; 'NAME' 

Deletes a named block from the memory pool 
memory reset [;router] 

memory reset deletes all memory blocks except those created with the router modifier. 
25 Using the optional modifier router causes all memory blocks to be deleted including those 
created with the router modifier. 



Example 
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memory rename; 'NAME'/NEWNAME' 



Renames a memory block 



memory resize; *NAME',size 



Changes the size of the named memory block. The memory block cannot be a fixed block. 



5 If the new size is larger, zeroed bytes are added to the end. if the new size is smaller, bytes are 
removed from the end. In either case, the remaining data is unchanged, 
memory info; 'NAME' 

Sets the system variable zmlength to the named block's size in bytes (or 0 if the block 
does not exist). If the block is of fixed type, sets the system variable zmstart to the block's 
10 absolute address in the memory pool. This command can be used to check whether a memory 
block of a certain name exists. 
Example 

zreturn checks are used to verify the existence of the memory block whose name is 
contained in the 8-byte variable test. If in the memory pool, its length and address (0 if not of 
1 5 fixed type) are displayed. 

memory info; test 

if zreturn $$ test for success (-1) 



write 



length= «s , zmlength » address = «s , zmstart» 



elseif 



zretum=10 



20 



write 



Name does not exist 



else 



write Other Error 



endif 



5NSDOCI0 <WO 9907007A2_I_> 



wo 99/07007 PCT/US98/15627 

305 

memory total; size ^ 

Changes the size of the memory pool. If the size is increased, additional memory is 
requested from DOS; if decreased/the unused memory is returned to DOS. By default, ail unused 
DOS memory (below 640K) is allocated to the memory pool; therefore it is not possible to 
5 increase the memory pool size unless it has been specifically limited by command line options 
when starting TenCORE. if a memory-resident program has been loaded after TenCORE, the 
memory pool size camiot be increased. 
Secondary Memory Pool 

When space runs out in the memory pool, existing blocks in the pool are automatically 
10 moved to the secondary memory pool to make room for new blocks. The secondary memory 
pool can be any or all of the following: expanded (EMS) memory, extended (XMS) memory, or 
disk. If more than one memory type is available, first expanded (EMS), then extended (XMS), 
and finally disk is used. 

When starting TenCORE, a default amount of available EMS, XMS, and disk space is 
15 automatically allocated to the secondary memory pool. If desired, the amount of each can be set 
upon system stanup. 

When a secondary memory pool is available, the maximum size of a block is still limited 
by the size of the main memory pool; however, more memory pool blocks can be created since 
existing blocks can be moved to the secondary memory pool. 
20 Creating fixed memory pool blocks limits the maximum size of ftjrther memory pool - 

blocks because they cannot be moved to secondary memory. In general, use of fixed memory 
_ blocks is not reconimended. 
System Variables 
zreturn 
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The memory command sets zreturn as follows: 



1 


Operation successful 




Variable reference out of range 


6 


Duplicate name 


10 


Name does not exist 


11 


Invalid type (resize of fixed block) 


16 


Invalid name 


18 


Insufficient memory in pool (create and resize keywords) or 




insufficient DOS memory to add to pool (total keyword) 



10 Miscellaneous 

The following system variables are set after any memory command which references a 
memory block name (except delete): 

zmlength Size, in bytes, of last referenced memory block 

zmstart Absolute address of last referenced memory block if fixed; 

15 otherwise 1 

The following system variables provide information about the TenCORE memory pool: 
zrmem Largest possible size for a new memory block that is not fixed 

zfmem Largest possible size for a new fixed memory block 

zmem Size of memory pool 

20 zxmem Amount of extra DOS memory which could be added to the 

memory pool (with memory total) 
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mode ^ 

Controls how graphics, text and images are plotted on the screen. 

mode mode 

mode SELECTOR; mode; mode;.,. 

5 write «mode 1 m, mode» 
The mode plotting keywords are: 

write use foreground color 

erase use background (erase) color 

rewrite use foreground color, erase character background 

10 inverse use background (erase) color, plot character background 

noplot simulates plotting without affecting the display 

xor use foreground color with EXCLUSIVE OR on existing display 

add use foreground color with OR on existing display 

sub use inverted foreground color with AND on existing display 

15 Description 

Controls how graphics, characters and images are put on the display screen. Each of these 
three types of objects has its own structure and interaction with the mode and color commands- 
Graphic objects such as draw and circle consist of the dots defining the object; they use the 
foreground color when plotting on the screen. Characters consist of foreground dots that define a 
20 character and the remaining background dots of the character cell: the foreground and 

* background dots perform different tasks in the various-modes using the foreground and erase 
colors. Images consist of a rectangular area of already colored dots and do not use the 
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foreground or background colors. However, a dot of color black (palette slot 0) in an imag^can 
be used for transparency to any pre-existing display. 

For text-only display screens, individual dots are not addressable: only whole character 
positions can be changed which limits the functionality of many of the modes. Text-only mode 
5 operations are discussed separately at the end. 

The mode is reset to the default mode upon a jump branch to a unit. The initial default 
setting for mode is write. This can be changed through use of the status save statement. 

A change in mode through an embedded mode command in a write statement does not 
extend beyond the write: upon finishing a write, the mode is restored to its value as at the start of 
10 the write. 

mode write 

Plots graphics and character dots in the foreground color. Images are plotted with their 
designed colors. Character backgrounds and the slot 0 color of images are transparent to any 
existing display. 
15 mode erase 

Erases graphics and character dots to the background (erase) color. Images are erased as 
for mode sub, 
mode rewrite 

Plots graphics and character dots in the foreground color. Character backgrounds are 
20 erased to the background (erase) color. Images are plotted entirely with their designed colors 
including the slot 0 color. 
Example 

A "count-down" is performed counting down from 10 to 0 followed by a "BANG!". 

mode rewrite 
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loop count <= 10,0,-1 ^ 

at 10:25 
showt count, 2 
pause 1 

5 endloop 

at 10:25 
write BANG! 

mode inverse 

Plots graphics and character dots in the background (erase) color. Character background 
10 is plotted in the foreground color. Images first have all colors inverted to their bit-wise 
complements and then are plotted entirely including color slot 0. 
mode noplot 

Simulates plotting without altering the screen. The screen location and all plotting 
attributes except mode are updated as though real plotting had occurred. 
15 Example 

The length of a line of text is first determined using mode noplot and put into the variable 
length This is done by setting the screen x position to 0 by an at, plotting the text in mode 
noplot, then getting the ending position found in the system variable zx. The text is then really 
plotted centered on the screen or display window. This is done in the last at statement by halving 
20 the display width (zxmax 12) then moving back by half the text width (length/ 2), 

mode noplot$$ do not affect screen 

at 0,100 $$ start at x=0 

write Handling Snakes $$ simulate plotting of text 

' calc length c= zx $$ the "system variable zx gives 

25 * $$ length of text 

mode write $$ set to standard plotting mode 
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at 2Xinax/2 - length/2,100 $$ set start of text ^ 

* $$ for centering 

write Handling Snakes 

mode xor 

5 Graphics, character dots and images are logically EXCLUSIVE OR combined with any 

existing display. Plotting the same material twice on the screen in the same location in this mode 
returns the display to its original composition. 
Example 

The word "ORBIT" is made to animatedly rotate around the center of the screen. If 
10 "ORBIT" runs through some background graphics, it would do so without altering the 

background, radxs defined as a real variable and holds the radian for the sin/cos calculations. 

screen vga 
calc rad c= 0 

mode 



15 loop 



20 



xor 
at 

write 
pause 
at 

write 
calc 



$$ switch to EXCLUSIVE OR plotting 



sin(rad)*100 + 320, cos (rad) *100 + 240 
ORBIT 
.01 

sin(rad)*100 + 320, cos(rad)*100 + 240 
ORBIT 

rad <= rad + .05 



endloop 

mode add 



Graphics, character dots and images are logically OR combined with any existing display. 
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mode sub ^ 

Graphics, character dots and images are color inverted and then logically AND combined 
with any existing display. 

Text-Only Hardware Screens 
5 The modes write, erase, rewrite and inverse work as expected changing the character 

foreground and background colors as appropriate. The logical modes xor, add and sub change 
the foreground character color as explained already. However, xor plots characters only where 
blank (space) characters already exist on the screen and otherwise erases characters from the 
screen. 

10 System Variable 

zmode Holds the current plotting mode 



0 


inverse 


I 


rewrite 


2 


erase 


3 


write 


4 


noplot 


5 


xor 


6 


add 


7 


sub 



20 move 

Moves bytes of data from a literal or variable into a variable. 



move from, to, length 
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Description 

Moves the specified number of bytes from one location to another, if bothj^-om and to are 
variables, they may overlap, and the length of data moved may exceed the defined length of either 
variable. The move command is extremely fast. 
Example 

Moves rec(2) through rec(5) down one record. 

define local 

reclen = 256 $$ TenCORE data record is ALWAYS 256 bytes 

rec(6) ,reclen $$ array of six records 

define end 



move rec(2), rec(3), 4*reclen $$ move the records down 

nextkey 

Advances system key input buffer and variables. 



1 5 nextkey [keyword] 




blank 


advances key buffer and updates zinput 


test 


updates zinput without advancing key buffer clear 


clears 


the key input buffer 


flags 


updates zinputf and zkeyset 


20 pointer 


updates zinputx, zinputy and zinputf, sets zinput to %ptrinfo 



Description 

nextkey reads pending keys from the system key input buffer. Input is normally buffered 
until the end of a main unit, a pause, an arrow, or a no judgment is encountered, nextkey checks 
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the input buffer immediately, without waiting for one of these waiting states. The blank tagTorm 
copies the next available key from the buffer into zinput and removes the key from the buffer 

If the key buffer is empty, the system variable zinput is set to zero. 

Encountering a nextkey does not activate current flow settings. 
5 nextkey 

Updates zinput, zinputf, and zkeyset with the next available key in the input buffer, 
removing the pending key from the buffer. If the pointer is enabled, zinputx and zinputy are also 
updated, 
nextkey test 

10 Updates zinput, zinputf; and zkeyset like the blank-tag form, but does not remove the 

pending key from the key buffer 
nextkey clear 

Clears the input buffer of all pending keys. Does not clear zinput. 
nextkey flags 

1 5 Updates zinputf and the left-most byte of zkeyset, and zeroes the right-most byte of 

zkeyset No change is made to zinputx and zinputy. 
nextkey pointer 

Updates zinutx, zinputy and zinputf. Sets zinput to %ptrinfo. 
Example 

20 The question "What goes meow?" is shown as an animated billboard at the top of the 

display. When the user presses a letter on the keyboard, the animation stops and the letter appears 
^ at the following arrow. The variable x is defined as a 2-byte integer. 

margin wrap $$ wrap around screen 

mode rewrite $$ replace any underlying text 
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calc X c= zxmax / 2 $$ start in middle of screen 

nextkey clear $$ clear any pending keys 

nextkey S$ clear zinput also 

+ 

5 loop zinput = 0 $$ loop while no input keys 

at x,zymax-20 $$ near top of screen 

write What goes meow? $$$ text will move to left in loop 
calc X <= X - 1 $$ move starting x to left 1 pixel 

calcs X < 0; x <:= zroax;;$$ check for screen wrap 
nextkey test $$ update zinput 



10 



endloop 



arrow 10,zymax-40 
answer cat 
1 5 endarrow 

System Variables 

zinput 0 no input 

1-255 character value of last keypress 
>255 non-character keypress 
20 zinputf Flags for the input in zinput 

zkeyset Flags and scan code for the input in zinput 

zinputx X-coordinate of the pointer device for the input in zinput 

zinputy Y-coordinate of the pointer device for the input in zinput 
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nocheck 

Cancels subroutine call argument count checking, 

nocheck return | receive 
nocheck return , receive 
5 return Turns off checking of argument counts for return commands 

receive Turns off argument count checking for receive commands 

Description 

Disables the automatic checking which is done on return and/or receive commands to 
insure that the correct number of arguments is being passed. 
10 nocheck allows any number of tags to be present in return or receive, regardless of the 

number of arguments specified by the calling (do, library, or jump) command. 

nocheck must be in the same unit as the return and receive commands to be affected (the 
called unit). 

operate 

15 Switches between different execution modes, 

operate mode 

operate SELECTOR; mode; mode;.. 
The mode keywords are 

source execute subsequent units from .SRC files 
20 binary execute subsequent units from BIN files 
tpr execute subsequent units from . TPR files 
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Description ^ 

Sets the mode of operation, source, binary or tpr, for system file execution. When a 
command executes which requires the system to access a unit, the mode of operation determines 
whether it looks for the unit in a source CSRC). binary (.BIN) or producer C TPR) file. The 
5 default is to access the same type of file as the current unit was loaded from. 

The operate command remains in effect until it is changed by another operate command, 
a library command, an error branch, or execution of a flow with an operate tag. 

If the mode is changed by a flow do, it is restored upon completion of the do sequence. If 
the mode is changed by flow jump, it is not restored. 
10 Executing operate source in the student executor generates execution error 1 1, "invalid 

argument value". 

error saves the mode of operation at the time the command is executed (at the time the 
branch pointer is loaded). When the error branch is taken, the mode of operation is reset to the 
mode which was in effect at the time the pointer was loaded. 
1 5 Interaction with library Command 

Execution of library temporarily sets the mode of operation to binary, if execution 
returns normally from the binary unit, the original mode of operation is restored. 

However, two things can prevent restoration of the original mode of operation: 

• entering a new main unit from a library unit, in which case no return from library 
20 occurs and binary operation continues. 

• executing an operate while in a library unit, in which case no restoration of the mode 
of operation is performed on return to the calling unit. If the calling unit was itself 
called by a library, the mode of operation is restored on return to that calling unit. 
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origin ^ 

Sets the origin for the display coordinate system, 
origin [LOCATION] 
Description 

5 Moves the origin for the coordinate system from the default location (0,0) to the specified 

location. All subsequent display commands are positioned relative to the specified origin. 

The origin is set to (0,0) at the stan of each new main unit. This can be changed using 
origin followed by status save; default. 
A blank-tag resets the origin to 0,0 
10 Example 

Displays a box inscribed with an x on three different areas of the screen. 



origin 

origin 120,70 $$ set origin for first box and x 

do xbox $$ plot it relocated 

15 origin 160,100 $$ second box 

do xbox 

origin 200,130 $$ third box 

do xbox 

xbox 

20 * this unit draws a 4 -pixel thick box with an "x" inside it 

* it is normally plotted in the lower left corner of the 

* display 
* 

box 0,0; 20, 20; 4 $$ draw the box 
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draw 



0,0;20,20;;0,20;20,0 $$ followed by x 



System Variables 



zorigmx 



Absolute X-coordinate for the current origin 



zoriginy 



Absolute Y-coordinate for the current origin 



10 



15 



outloop 

Exits a loop structure from any point within the structure, 
outloop [CONDITION] 
Description 

Provides an exit from any point within the loop structure. If the tag is blank or the 
condition is true, outloop goes to the command following the associated endloop. If the 
condition is false, no action is taken and execution continues with the next command within the 
loop structure. 

outloop always appears at the same indentation level as the loop structure to be exited, 
regardless of any other indented structures surrounding the outloop. 
Example 

define local 

counter, 2 $$ counter 

define end 

local 
* 

at 5:3 

write Press Enter to increment the counter, or 



Esc to exit the loop. 



calc 



counter c= 1 
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loop 



at 8:3 



50 



write The counter value is «show, counter». 

5 , pause pass= %escape, %enter 

outloop zinput = %escape $$ exit if Esc is pressed 

calc counter <= counter + 1 

endloop 
* 

10 at 10:3 

write You exited the loop! 



pack, packz 
packc, packzc 



Places text string into buffer. 



15 pack buffer; [ length ]; TEXT 

packz buffer; [ length ]; TEXT 

packc SELECTOR: buffer; [ length ]; TEXT; TEXT;,,. 

packzc SELECTOR; buffer; [ length ]; TEXT; TEXT;.,. 

buffer A variable into which a text string is placed. 

20 length An optional variable that is assigned the number of characters placed into the buffer 

TEXT The text string to be placed into the buffer. 

SELECTOR An expression used for selecting one of the TEAT cases. 
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Description ^ 

Places a text string into the given buffer and if a length variable is specified, returns the 
number of characters actually stored. If the defined buffer is longer than the text string, the pack 
form leaves the extra bytes unchanged while the packz form zeroes them. A c (conditional) suffix 
5 on the command denotes the SELECTOR form. 

The text string can contain embedded show-type commands such as show, showt, and 
showa. If the text extends beyond one line, a carriage return (code 13) is packed into the buffer 
before each additional line. If the text string continues over blank lines, multiple carriage returns 
are included. If the length of the text string is not required, use a null argument for length. 
10 The pack commands do not perform bounds checking: characters being packed can 

overrun a buffer and overwrite subsequent variables or cause an execution error if they extend 
beyond defines. The maximum possible length of a text string must be allowed for. 
SELECTOR Delimiters 

The delimiter following the length argument is used by packc and packzc to delimit the 
15 text strings for each case. The following delimiters are valid: 
comma , 
semicolon ; 
colon : 
end-of-line J 
20 universal delimiter j 

Two consecutive delimiters indicates a null tag; nothing is packed into the buffer for the 
corresponding value of SELECTOR. If a delimiter other than end-of a line is being used, a single 
string can span more than one line, in which case a carriage return is packed in for each end-of- 
line encountered. 
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Null Codes 

.\ny null characters (code 0) in an embedded showa command are skipped; the null 
characters do not appear in the resulting string. Null characters can be forced into a packed string 
by using an embedded showv command with a variable that contains the null characters. 
5 Examples 
Example 1 

Puts three lines of text into the buffer lines. They are separated by carriage return codes in 
the buffer, count is set to the length of the string packed. The showa statement would display the 
three line text string. 

10 pack lines ; count ; The first line of text. 

The second line of text. 
The last line of text, 
showa lines, count 

Example 2 

15 Embedded commands are used to include the name in buffer name and integer in variable 

age within the text string being packed into buffer introbuf Any extra space in introbitfis zero 
filled. No length argument is used. The showa statement would display a message such as "My 
name is Alex. I am 23 years old." Any following zero codes in introbuf are skipped by the system 
plotting routines. 

20 packs introbuf; ;My name is «a,name». I am «s,age» years old. 
showa introbuf 

Example 3 

Based on variable number, the text negative, zero, or positive is conditionally placed into 
textBuf stxxmg count to the number of characters transferred. End-of-line is used as the 
25 SELECTOR dehmiter. Unused space in textBuf is zero filled. 
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packxc number ;textBuf; count 
negative 
zero 

positive 
5 Example 4 

The buffer textDate is set to a character string with today's date (for example "January 1, 
1993"). The variable temp is used to hold the month until it is packed into textDate along with the 
day and year. Note the three null arguments on the packzc command: the first indicates no length 
information is required; the next two handle the SELECTOR negative and zero cases which are 
1 0 not possible with month. 

define local 
today , 4 

year , 2 

month , 1 
15 . day, 1 

ten^, 9 
textDate, 20 
define end 

20 date today $$ obtain the system date information 

* 

packzc month;teinp; ; ; ; January /February ;March; April ;May; June ; July /August ; 
September ; October /November /December 

* 

25 packz textDate// «a,teit^» «s,day», «S;year» 
* 

at 5:10 
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showa textDate $$ display today's date ^ 

page 

Selects the hardware screen page to use for plotting and display. 

page showpage [ ,writepage ] 
5 showpage page number to display 

writepage page to plot on 

Description 

Some display hardware has several separate, complete displays called pages. The page 
command is used to control them. 

The one argument form of page changes the active display page to the one specified. The 
contents of that page are displayed immediately and all further plotting occurs on that page. 

The two argument form causes the page given first to be displayed while the page given 
second is used for all further plotting activity. This allows the program to construct a new, hidden 
page in memory while the user is viewing the displayed page. 

Entering a new main unit erases only the page selected for plotting. 
The number of pages available depends on the display hardware being used, the display 
memory available, and the screen resolution selected. The system variable zmaxpage contains the 
number of pages that the current screen supports. 
Example 

Animates an image named fish in mode xor. Because redisplaying an object in mode xor 
removes it cleanly from the display, mode xor is used when an animated object must pass over 
other objects without destroying them. Without page, mode xor animations usually show too 
much flicker to be useful. 
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Page 1 is used to show the image at odd x-locations 201, 203, 205, etc. ^ 
Page 2 is used to show the image at even x-locations 202, 204, 206, etc. By alternating 
pages, the image is made to appear at 201, 202,203, 204, 205, 206, etc. 

screen ega, graphics , medium , color 
5 define local 
X, 2 

define end 

* set mode and load image into memory 
mode xor 

10 image move; block, 'fish'; memory, 'fish' 

* display the first image on page 1 
image plot; memory, * f ish ' ; 201,100 . 

* while displaying page 1, 

* erase page 2 and put the next image on it 
15 page 1, 2 



erase 



xmage 



plot; memory, 'fish'; 202,100 



loop 



X c= 201,400 



* show page 2 while changing the display on page 1 



20 



* ... re -display (thus removing) the old fish on page 1 



* . . .and display a new fish 2 pixels to the right on page 1 



* then increment x-location counter by 1 



page 2 , 1 



image plot; memory, 'fish'; x,100 



25 



image plot; memory, 'fish'; x+2,100 



calc X c= X + 1 



keep page 1 showing while changing the display on page 2 



page 1 / 2 
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image plot; memory, 'fish'; x,100 ^ 
image plot; memory, 'fish'; x+2,100 

endloop 

System Variables 



5 


zrpage 


Page currently displayed 




zwpage 


Page on which text and graphics is being written 




zmaxpage 


Maximum number of pages available for screen type in effect 




palette 






Changes the palette. 


10 


palette keyword 






init 


initializes the palette to the default state 




set 


sets color values for individual palette entries 




read 


reads palette entries from hardware to variables 




write 


writes palette entries from variables to hardware 


15 


color 


associates a color keyword with a palette entry 



Description 



Changes the set of colors available on palette-based display hardware: EGA, MCGA, 
VGA, EVGA and compatible graphics adapters, palette supports several different functions: 

• Changing all or a ponion of the current palette 

20 • Reading all or a portion of the current palette setting into variables. 

• Changing a color keyword to correspond to a'diflferent palette entry. 
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A "palette" is the set of colors assigned to the hardware color slots. VGA screens hive 16 
color slots, and MCGA and EVGA screens have 256 color slots. The "standard palette" is the set 
of default values for those slots. 

Each color is a combination of three color values: red, green, and blue. Together, they are 
5 referred to as RGB. Some modes also use an intensity byte to indicate relative brightness for each 
color. For TenCORE, the standard palette uses the following color assignments: 



0 


black 


4 


red 


S 


black+ 


12 red+ 


1 


blue 


5 


magenta 


9 


blue+ 


13 magenta+ 


2 


green 


6 


brown 


10 


green+ 14 


brown+ 


10 3 


cyan 


7 


white 


11 


cyan+ 


15 white+ 



There is no inherent connection between a slot number and the RGB values that it 
contains. This is relevant when displaying more than one image on the same screen. If the images 
use different palettes, only the palette of the most recently displayed image will be active. Since 
the same slots are in use by the other images, their colors might change when a different palette 
1 5 becomes active. Careful planning of a common palette for multiple images on a screen is needed. 

The default palette is restored whenever a new main unit is entered. The default palette 
can be altered by executing a status save with the palette modifier after changing the palette. 
The palette is reset to the standard default by executing a status restore;standard;palette. 
palette init [ ;number ] 

20 Initializes the palette to its standard default state. On cards that support multiple defaults, 

number specifies the desired default palette, 
palette set; COLOR, red, green, blue, [ ,intensity 1 

Sets the values of red, green, blue, and optional intensity for the palette slot referred to by 
COLOR. Palette slots can be specified by number or color keyword. 
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COLOR is any hardware color number valid for the hardware in use. red, green, bkre and 
intensity range from 0 to 255. For hardware which does not support so wide a range, the values 
are automatically scaled: 255=flill intensity, 128=half, etc. The system variable zpalincr reports 
the minimum significant increment for the color values; zintincr gives the minimum significant 
5 increment for intensity. 

intensity is significant only for two screen types: ega,graphics,Iow and 
ega,graphics,medium. On other screen types, zintincr is 0 and the intensity value is ignored. 
This can cause problems when a palette originally generated on either of these two screen types is 
used on another screen type: it can result in a "dimming" of the palette on the new screen type. 
10 This is because the intensity is no longer available, and must be corrected by adjusting the RGB 
values of the palette, 
palette read; bufTer, number 

Reads the requested number of palette entries into the variable buffer. The stnacture of 
the buffer is explained below. 
15 palette write; bufTer, number 

Writes the requested number of palette entries from a variable buffer. The structure of 
buffer is explained below, 
palette color; COLOR, slot 

Associates a TenCORE color keyword with a palette slot. The TenCORE color names by 
20 default correspond to the first 16 palette slots. The color option allows the author to change 
which palette slot corresponds to a given color name. 
Palette Variables 

The read and write keywords allow palette slot entries to be read to or written from a 
buffer. The palette buffer contains one or more 6-byte palette entries of the form: 
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slot (2 bytes) 
red (1 bvte) 
green (1 byte) 
blue (1 byte) 
5 intensity(l byte) 

The value of slot must be set for each palette entry before executing the read or write. 
Any subset of palette entries may be read or written by setting appropriate slot values. 
Example 

To read the palette information for the default 16 TenCORE color slots: 

10 define local 
palette (16) , 6 

slot, 2 
red, 1 
green , 1 
15 . blue, 1 

intensty, 1 
count / 2 
define end 
* 

20 loop count <= 1, 16 

* must remember to initialize slot numbers 

calc slot (count) <= count - 1 

endloop 

*• 

25 'palette read; palette (1), 16 
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System Variables ^ 
zpalincr Minimum significant increment in color values for current screen type 
zintincr Minimum significant increment in intensity values for current screen type 

pause 

5 Pauses execution until event occurs. 

pause [ time;] [now= all | KEY/s;] [ pass=all | KEY/s ] 
pause [ time;] testkeys= all | KEY^s 

time delay time in seconds before continuing execution 
flow= key list for flow branching 
10 pass= key list to continue execution 

testkeys= like pass= but key not removed from input buffer 

Description 

Stops execution of commands until an accepted event, such as a keypress, occurs. The 
keypress can pass the pause and continue or perform flow defined key branching. When a 
keypress is handled by pause it is normally removed from the input buffer and the system input 
variables such as zinput are updated to reflect the new event. 

Any break modified flow branch always works: it interrupts any pause to perform its 
task. Other flow branches are active at a pause only if their keys are specified in the flow= 
keylist. In either case, if the flow is a do or library branch, control returns to the pause when the 
subroutine ends. 

If a time is specified, it sets a clock running that issues the default %timeup key when the 
time expires. This %timeup key is automatically included in the pass= keylist; unless some other 

9907007A2_I_> 
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accepted event occurs first, the %timeup allows execution to continue. If a flow do or flow 
library branch occurs during a timed pause, timing is suspended until the subroutine returns 
control to the pause, then timing resumes. 

A pause command can extend over several lines if needed to list all options; a blank 

5 command field signifies continuation, 
pause 

A pause command with no tag waits until any event occurs at which time command 
execution continues. It provides for a temporary program halt: the user presses any key and the 
program continues. Only break modified flow branches alter the inevitability of executing the 
10 next command. 
Example 

write Press Any Key to Continue 
pause 

write Good, now let's open the valve and see what happens... 

15 pause time 

A pause command with only timing forces a delay for the specified time. Only break 
modified flow commands can interrupt the time delay. Any other events are ignored and removed 
from the key input buffer. For a forced delay that doesn't empty the input buffer of events 
occurring during the delay, use the delay command. 
20 There is only one default timer key used for both the pause and time commands: 

%timeup. Timing in the pause supersedes any default time set by a previous time command. 
Example 1 

'at 5:10 
write Some text. . . 
25 pause 5 
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at 7:10 

write Some more text. , . 

After a 5 second delay, additional text is added to the display. 
Example 2 

5 flow do; %f5; data; break 

time 30 
pause 5 

10 The program is paused for 5 seconds: the previous timing (time 30) is cancelled. If [F5] is 

pressed, the timing is suspended while the break modified flow branch to unit data is done. Upon 
return, the pause waits for the remaining time, 
pause [ time ;] flow^ all | KEY/5 

A pause with a flow^ keylist allows only the specified or all flow branches to work. If a 
15 do or library branch occurs, control returns to the pause command when the subroutine ends. 
Optionally, timing can be used to end the pause after a given number of seconds, break modified 
flow branches always take precedence, whether or not they are listed. 
Example 1 

pause flow=all 

20 The program is paused until any flow branch occurs. Coding following the pause will 

never be executed. 
Example 2 

flow jump; %fl; out 

-flow do; %f2; info 

25 flow do; %f3; data 
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pause 10; flow== %fl, %f2 

The program is paused for 10 seconds unless [Fl] is pressed to jump to unit out If [F2] 
is pressed, timing is suspended while unit info is done as a subroutine. Upon return from unit 
info, the pause waits for the remaining time. Unit data is not accessible from this pause since its 
5 branch key is not in the flow= keylist. 
pause [time ;1 pass= all 1 KEY/s 

A pause with a pass= keylist allows the specified or all keys to pass the pause to 
continue execution of the following commands. Optionally, timing can be used to end the pause 
after a given number of seconds; the resulting %timeup key is an automatic entry in the pass= 
10 keylist. Only break modified flow branches work here and take precedence over any keys in the 

pass= keylist. 
Example 1 

A choice page allows the user to choose a subject for study. Upon choosing one of the 
options at the pause, the program continues to branch (with arguments) to the appropriate 
15 section of the lesson. The break modified branch to unit index is the only flow branch which can 
occur at the pause. 

flow juit^i; %fl; index; break 

flow juit?>; %f2; notes 

20 write Choose an option: 

a. anthracite coal 

b. bituminous coal 

c. peat 

'pause pass= a, b, c $$ only accept a,b,c 

25 if zinput « "a" 
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unita (3,5,1) 



elseif 



2 input 



$$ et cetera 



Example 2 



pause 



10,pass=a,b,c,d,e,f ,g,h,i, j ,k ,l,m. 



10 



15 



n/0,p,q,r ,s , t,u,v,w,x,y,z, 
0,1,2,3,4,5,6,7,8,9 

The tag of a pause command can extend over several lines. This pause waits for 10 
seconds or until one of the listed keys is pressed. 
Example 3 

write Lots and lots of text 

over many , 

many lines . 
nextkey clear 
pause pass=a,b,c 

If there is time consuming coding such as a large display, keys might be stacked up in the 
input buffer before a pause command is executed. The pause processes these waiting keys until it 
comes to one that it passes. This can be desirable sometimes since it allows the user to type 
ahead. If type ahead is not desired, use a nextkey clear statement before the pause. It empties 
the key buffer of all pending keys, 
pause [ time ;] flow= all | KEY/s ; pass= all | KEY/s 

Both the now= and pass= keylists can occur in the same statement with pass= keys 
taking precedence over now= keys. Optionally, timing can be used to end the pause after a given 
-number of seconds, break modified flow branch keys work in all instances. 
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The pseudo-key value %other can be placed in either keylist to include all keys thafare 

not individually assigned. If put into the flow= keylist (or by use of the all keyword), then any 

flow statement with the %other pseudo-key is activated. 

Example 1 
5 pause flow=all; pass=ftother 

All How keys are active. All other keys pass the pause to continue execution of the unit. 

Example 2 
flow juinp; %timeup; timeout 

10 time 10 

pause flow=all; pass=a,b,c 

Timing here has been set before and not overridden by the pause statement. When the 

system generates a %timeup key, a flow branch to unit timeout occurs. 

Example 3 
15 flow jump; %fl; =exit 

flow juir?); %f2; index 

flow do; %f5; data 

flow juiti^s; %timeup; timeout 

20 pause 10; f low=all ; pass=a,b , c , %pointer 

Pressing [A],[B] or [C] or any pointer dick passes the pause to the following command. 
Any of the specified flow keys (but %timeup) perform their defined flow fiinctions. If no other 
accepted event occurs for 10 seconds, execution continues with the command following the 
-pause. Control does not pass to unit timeout since the-pause command's timing automatically 
25 includes %timeup in the pass= keylist, which takes precedence over flow assignments. 
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Example 4 ^ 

flow juitip; %fl; =exit 

flow jump; %f2; index 

flow do; %pgup,%pgdn; nextunit 

5 flow do; %other; badKeys 

pause flow=all; pass=a ;b , c , %space , %f 2 

Pressing [A],[B],[C] [] or [F2] passes the pause to the following command. The %f2 flow 

branch is not taken because the key is in the pass= keylist which takes precedence. The %fl flow 
10 branch and any other flow branches work because of the now=alI. Any key not included in the 

pass= keylist and not defined in other flow statements performs the flow do to unit badKeys 

which handles unanticipated keys. 

pause { time ;] testkeys= all | KEY/s 

The testkeys= form is similar to pass= except that passed keys are not removed from the 
15 input buffer. It is used to test pending input since the system input variables such as zinput are 

updated. The passed key remains in the input buffer until a following input processing point 

(pause, arrow, nextkey, end-of-unit). testkeys= is the pause form of the nextkey test 

command. 

testkeys= cannot occur with any other of the keylist forms. 
20 Example 

pause testkeys=0 ,1,2,3,4,5,6,7,8,9 

long 1, judge 

arrow 10 : 10 

answer 3 

25 . write Great! 

wrong 2 
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write No, that*s Mars. ^ 

wrong 1 

write No, that's Mercury. 

5 endarrow 

Only the number keys cause termination of the pause. Since the passed key is not 
removed from the input buffer by the testkeys= form, it remains as input for the following arrow. 
After displaying on the screen at the arrow, the key immediately causes judging to occur due to 
the long 1, judge. 
10 Obsolete Form 

The ambiguous keys= form of the previous version of the system is now replaced with the 
explicit pass= and flow^ keylist forms. It was not possible by looking only at the keys= keylist to 
predict whether a listed key would perform a flow branch or pass the pause to the next 
command. While the keys= form still works for reasons of upward compatibility, users are 
1 5 advised to switch to the new unambiguous forms. 
System Variables 

The input-related system variables are updated whenever pause processes a key. 
zinput Most recent keypress, pointer input, or pseudo-key 

zinputa Area ID causing current zinput value 

20 zinputf Bitmap of keyboard conditions at time of event 

zinputx Pointer x-coordinate at time of event 

zinputy Pointer y-coordinate at time of event 

zkeyset Keyboard scan code 

zpcolor Color of screen under pointer at time of event 
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perm 

Manages permutation lists, 
perm keyword... 





create 


generates permutation list in memory 


5 


next 


gets next number from permutation list 




remove 


removes specific number from permutation list 




replace 


puts specific number back into permutation list 




copy 


makes copy of permutation list 




delete 


deletes permutation list from memory 


10 


reset 


deletes all permutation lists from memory 




read 


reads permutation list into variables 




write 


writes list in variables to permutation list 



Description 

The permutation managing options available through the perm command allow for the 
15 random selection, removal and replacement of a number from a list of numbers. Multiple 

permutation lists can be accessed simultaneously. Copies of a list can be saved and restored at 
any time in memory or even to the disk between sessions to allow for any possible strategy in 
using permutations. 

Permutation lists can be created in the one system default buffer or in any number of 
20 named buffers. If possible, the use of the default buffer simplifies using permutations since the 
' name argument can be eliminated. The default buffer for the perm command is shared by all 
units. 
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Permutation list buffers are kept as memory blocks in the memory pool. The memory pool 
is used by the commands: memory, image, window, status, area, flow, font and perm. 
Memory blocks are tagged as belonging to a specific command type at creation and cannot be 
accessed by other commands using the memory pool; different commands can use the same name 
5 for a memory block without conflict. 

perm create; length [; *NAME' ] default j 

Creates a permutation list of non-repeating, randomly-ordered integers fi-om 1 to the 
specified length (maximum 32,767), The list is stored as the default or a user named buffer in the 
memory pool. Creating a new default list automatically supersedes any previous use of the 
10 default buffer. Creating a named list produces an error if the named list already exists; use the 
delete option first if you wish to use the same name again. 
Example 1 

Creates a default permutation list of integers from I to 10. 

pena create ; 10 

15 Example 2 

Creates a permutation of integers from 1 to 25; the list is saved in the memory block 

named quiz I. 

perm create; 25; 'quizl' 

perm next; variable [; ^NAMF 1 default ] 
20 Randomly selects a permutation number and stores it in a variable. The number selected is 

removed from the permutation list If the permutation list is empty or an error occurs, 0 is 
returned. 
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Example 1 ^ 

Gets the next number from the default permutation list and puts it into the variable 
question; the number is removed from the list. 

perm next ; question 

5 Example 2 

Like Example 1 but the number comes from the named list quizl 

perm next; question; 'quizl' 

Example 3 

A permutation of 5 items is created in the default buffer Within a loop, the five questions 
10 in units 01 through 05 are presented in random order. When the list is exhausted, the 0 value in 
variable question is used to exit the loop structure. 

perm create; 5 $$ create default permutation list 

jump zreturn; ; error 

loop 

15 . perm next; question $$ get next permutation number 

do question; ; ;Q1;Q2;Q3;Q4;Q5 $$ call question 

outloop question =0 $$ exit loop if done 

endloop 

perm remove; ItemNumber [; 'NAME' | default ] 
20 Removes the specified item from a permutation list. The integer is no longer available for 

selection by a perm next statement. 
Example 

Removes the value in problem from the default permutation list. 

*perm remove; problem 
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perm replace; itemNumber [; 'NAME' ] default ] ^ 

Puts the specified item back into a permutation list. The integer is available again for 
selection by a perm next statement. 
Example 

5 Puts the value in problem back into the default permutation list 

perm replace; problem 

perm copy; [ TROiM' | default ] ; [ 'TO' | default I 

Makes a copy of a permutation list. If the copied-to list already exists, it is overwritten. 
The default list can occur only once in the statement. 
10 Example 1 

Copies permutation list first into the named list second. 

perm copy; 'first*; 'second' 

Example 2 

Copies the default permutation list to the list named in the variable newList 

15 perm copy; default; newList 

perm delete [; 'NAME' | default ] 

Deletes a permutation list from memory. 

perm reset 

Deletes all permutation lists from memory. 
20 perm read; permBuffer [,length ] [; 'NAME' | default ] 

Reads a permutation list into the specified buffer for a given length in bytes. If length is 
not specified, the defined length of the buffer is used. 

The read and write forms of the perm command are for use in saving and restoring a 
permutation list on the disk between learner sessions. 
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The structure of the buffer is as follows: 



Item 


Bvtes 


Version of perm 


2 


Length of list 


2 


Number of remaining items 


2 


Item bitmap 


N 



The item bitmap is formatted such that each bit corresponds to a number in the 
permutation list: if the bit is " 1 the item is still available; 0 indicates it has been removed. For 
example, if bit 3 is set to 1, the number 3 has not yet been removed from the permutation list. The 
5 length of the item bitmap is determined by the length of the list. Since each byte can hold the 
status of 8 items, N is the length of the list divided by 8, rounded up. It can be computed as 
int((length+7)/8) or ((length+7) ^ 8). 
perm write; permBufter [,lengthl I; 'NAME* | default J 

Writes a given length of bytes from a buffer into a permutation list. If the length is not 
10 specified, the defined length of the buffer is used. 
System Variable 
zreturn 



- 2 Redundant operation: replace used with number already in list or 

remove used with number already removed 
15 -1 Operation Successful 

3 Out of range: attempt to create list larger than 32,767 or attempt to 

remove or replace number larger than list size 
6 Duplicate name using create 

10 Name not found 

20 1 7 Attempt to write invalid permutation list data 

1 8 Insufficient space in memory pool 



BNSOOCID: <W0 9507007A2_1.> 



wo 99/07007 PCT/US98/15627 

342 

polygon 

Draws a polygon 

polygon [ LOCATION ]; [ LOCATION ]; [ LOCATION ] ... [ ;fill ] 
Description 

5 Draws a polygon in the foreground color using the specified LOCATION as vertices. 

The optional modifier fill specifies that the polygon be filled. Only convex polygons can be filled; 

concave ones must be split into multiple convex ones (see below). A minimum of three points 

must be specified. A maximum of 50 points may be specified. If the last point does not match 

the first, they are connected. 
10 A polygon is affected by scale, rotate and width. Filled polygons fijnction only when any 

horizontal line intersects exactly two points on the polygon. 

Splitting a concave polygon into multiple convex polygons will produce the desired shape 

polygon 0,100; 200,0; 200,100 $$ draws a triangle 

polygon 10:10; 10:20; 20:20; 20:10 $$ draws a rectangle 
15 polygon 0,100; 200,0; 200,100; fill $$ draws filled polygon 

press 

Generates an input value, 
press KEY I expression [;first] 

press KEY \ expression [,inputF [,inputX,inputY [,inputA ] ] ] [; first ] 

20 Description 

The press command puts a specified key into the input buffer as if pressed on the 
keyboard. At the next input-processing point (pause, arrow, nextkey, or end-of-unit), the key is 
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processed and performs whatever function a similar real keypress does including the update of the 
system variable zinput 

The optional modifier first causes the key to be inserted before any other keys waiting in 
the input buffer: it will be processed first. 
5 Optionally, the values for the system variables zinputf, zinputx, zinputy, and zinputa 

can be specified so as to be set along with zinput when the key is processed. If a value is not 
specified, the corresponding system variable is set to zero. 

The values for press are limited: embedding and the simple a,b,c form are not 
available. However, the key can be an expression such as a constant, variable or calculation. 
10 Examples 
Example 1 

Puts %space into the input buffer as if it had been pressed on the keyboard. 

press % space 

Example 2 

15 Places %F1 in the input buffer before any other keys waiting to be processed; it will be 

processed first. 

press %F1; first 
Example 3 

Simulates a pointer click by placing the key value %pointer along with location and area 
20 id information into the input buffer. At the next input-processing point, 2input=%pointer, 

2inputx=320, 2inputy=240, and zinputa=5. Since no value is specified for zinputf, it is set to 0. 

press %pointer, ,320 ,240 ,5 

Example 4 

After an unsuccessful try at the question, the learner is given the first few letters of the 
25 correct answer typed in as input to the arrow. 
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write Who is buried in Grant's tomb? 
arrow 

answer «U , Ulysses , S» Grant 
no 

write Press any key for a hint 
pause 

press %enter 
press %"G" 
press %"r" 

1 0 endarrow 

System Variable 
zreturn 

-I Operation successful 

0 Key buffer overflow 



$$ erases the mistake 



15 print 



Sends output to the printer, or changes print parameters. 



print variable, length 

print initial; prn | Iptl I lpt2 1 lpt3 1 coml 1 com2 

print initial ; file, 'FILENAME' [ ,length ] 

20 print end 

bufifer variable buffer to output to printer 

length number of bytes to send to the printer 

initial changes the printer device 

end ends network spooling and resets printer to Iptl 
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Description 

Seads the specified number of bytes to the standard printer device Iptl, or to another 
device or file specified by print initial. 
Legal devices for print are: 
5 prn, Iptl, Ipt2, Ipt3, coml, and com2. 

The initial keyword changes the device used for printing. With the file form, a file name 
is specified. The ASCII filename string may include a drive and path, and must be terminated with 
a null byte. If the length is not specified, the defined length of the variable is used. 

If the specified file already exists, it is initialized to 0 length in preparation for printing. 
10 The end keyword clears any printer connection established with print initial. On a 

network system, it also terminates printer output spooling and initiates printing. 
Unless otherwise specified by print initial, output is sent to Iptl. 
print only sends the specified characters to the printer. Printer control characters are not 
added to the output. Refer to the manufacturer's manual for printer control codes. 
15 Most printers require an ASCII carriage return code (hOd) or a carriage return/line feed 

sequence (hOdOa) at the end of each line to position the print head and paper for the next line. 

Technical Note: When no printer connection is in effect, printer output is sent to the 
BIOS INT I7H printer driver, device 0 which is normally Iptl unless it has been redirected. 
When a printer connection is active, printer output is sent to the device via the standard DOS 
20 "write" call. 

Examples 
Example 1 

Prints the title line for a report. The user's name is stored in iisemame. Note that a 
carriage return/line feed sequence is included. 
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define local 

username, 20 S$ name of user 

text; 100 5$ text to print 

texten, 2 $$ length of text to print 

5 CRLF = hOdOa $$ carriage return and line feed 

define end 

packz text ;textlen; Test results for «showa ,usernaine» 
« showa,CRLF » 

10 * 

print text, textlen $$ print the line 

Example 2 

Redirects future printing to lpt2. 

print initial; lpt2 $$ initialize lpt2 

15 Examples 

Redirects future printing to file C:\TENPRINT.PRN 

define local 
filename, 40 
define end 

20 packz filename ;;c:\tenprint.prn $$ put filename in variable 
print initial; file, filename $$ redirect output to file 

System Variable 
zreturn 

_ I Operation Successful 

25 0 Disk error (see zdoserr and zedoserr) 



wo 99/07007 



347 



PCT/US98/15627 



put 



Substitutes one string of characters for another. 



put fromTEXT: to TEXT [ ,bufFer [ jength ] ] 



JromTEXT text string to find and replace 



toTEXT replacement text sting (can be null) 



buffer 



user variable buffer on which to perform replacement 



length 



maximum length for buffer 



Description 

Replaces every occurrence of fromTEXT with /o TEAT in the student response buffer at an 
arrow or optionally in any specified buffer. The TEAT occurs without quotes and can contain 
embedded show commands. 

Examples 

Example 1 

Shows how put can be used to change an abbreviation to its full word equvalence in 
answer judging. 

write What is the biggest US city? 

arrow 10 : 10 

put NY, New York 

answer New York 



write 



Great! 



endarrow 



Example 2 



Replaces all occurances of "dog" with "elephant" in the buffer mystring. 



put 



dog , elephant , mys tring 
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10 



15 



Example 3 " 

Embedded text can be used for both tht from and to strings. 

pat «a , oldchars , oldlen» , «a , newchars , newlen» , textvar , length 

Example 4 

This produces a 24-hour type clock display. If the hours or minutes are less than 10 the 
tens digit would contain a space from the showt's of the pack. The put replaces any spaces in 
var with the digit 0. 

pack var, length, «showt, hrs , 2»:«showt, mins, 2» 

put ,0, var, length $$ from string is just a space 

^ replace spaces with 0 

showa var , length 

System Variables 
zreturn 

.1 Operation successful, all possible replacements made 

0 Insufficient room for replacement 

Miscellaneous 

zlength Length of the text string after replacement 
znumber Number of replacements made 
zcount Length of response buffer, if used 



20 receive 



Receives argument values passed to a subroutine 



, receive argument/ 16s 
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Description ^ 

Receives arguments passed to a subroutine unit and places their values in the specified 
variables. Null arguments are specified by blank entries („)in the argument list. 

Arguments can be passed by do, library, jump, and jumpop commands. The following 
5 appHes to receive: 

• Any element in the argument list may be null. A null element in the argument list 
causes the corresponding passed value to be ignored. 

• A litteral used as a receive argument causes a condense error. 

• Only numeric integer and real variables are valid in the argument list; A text 
10 variable of eight characters or less is considered a numeric in this context. 

• Any number of receive commands may be executed, and any receive may be 
executed an arbitrary number of times. Each time a receive is executed, the 
originally passed arguments are used. 

• Intervening calls to other units (which can receive or return their own arguments) 
15 have no effect on the values received in the current unit (passed values are local to 

the individual units). 

• If a null argument is sent, the corresponding element in the receive list is not 
changed. 

• Normally, the number of arguments received must match the number passed, 
20 otherwise an execution error occurs. This can be overridden by using nocheck 

receive. 

Example 

Unit oy\e passes arguments to subroutine circles. 
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one 



5 do circles (160, 100, 5) 



circles 

10 define iocaJ. 

X, 

n, 
r , 



2 $$ center of circles 
2 

2 $$ nuinber of circles 

2 $$ radius of circle 



1 5 define end 

receive x, y, n 

at x,y 

loop r <= 10, n * 10, 10 

20 . circle r 
endloop 

System Variables 

zargsin Number of arguments (including nulls) sent to subroutine 

zargsout Number of return arguments expected 
25 zargs Number of non-null arguments actually received 
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reloop 

Returns to the beginning of a lOOP structure, 
reloop [CONDITION] 
Description 

Used to restart the loop structure. If the tag is blank or the condition is true, reloop 
returns to the beginning of the loop structure as if endloop had been executed. If the condition is 
false, execution continues with the next command, reloop always appears at the same indentation 
level as the loop command to which it returns, regardless of any other indented structures 
surrounding the reloop. 

For more information on loop structures, see the loop command. 
Example 

An ITERATIVE loop which skips the case when the counter is 13. 

define local 

index, 2 $$ loop counter 

define end 

* 

loop index c= 1,20 

reloop index = 13 
at index: 5 

write This is line «show, index» . 

endloop 
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return 

Ends subroutine execution optionally returning arguments. 



return [ argument/ 16s] 



Description 

5 Exits immediately from the current unit if it was called by do or library. If the unit was 

not called by a do or library, an execution error occurs. 

The blank-tag form causes an exit from the unit with no arguments passed back to the 

calling unit. 

If a list of return arguments is specified, the values are returned to the calling unit. A null 
10 entry in the return list causes the corresponding value in the receive argument list to remain 

unchanged. 

See the receive and nocheck command descriptions for more information on argument 

passing. 

Example 

15 Unit test calls subroutine square, passing it one argument; subroutine square receives that 

argument, uses it in a calculation, then returns the resulting value to the variable numsquar back 
in unit test 
test 

20 . 

do square (12; numsquar) 

show nimsquar 



BNSDOCID <W0 9Q07007A0 I ^ 



wo 99/07007 PCT/US98/15627 

353 

square 

define local 

nuiciber 

5 number 2 

define end 
★ 

receive number 

calc number2 c= number * number 

10 return number2 

System Variables 
Miscellaneous 

zargsin Number of arguments, including nulls, sent to subroutine 

zargsout Number of arguments the calling do or library expects returned 
15 zargs Number of non-null arguments actually received by receive 

rotate 

Rotates subsequent graphic objects. 



rotate [ degrees [ J^OCA TION ] ] 



Description 

20 Causes all subsequently plotted graphic objects to be rotated by the specified number of 

degrees. Rotation occurs counter-clockwise about the plotting origin, as specified by the origin 
•command, unless an optional location is specified. Specifying a rotational origin affects only 
subsequestly rotated objects. 
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The system default is rotate 0 (no rotation), set at each main unit and by initial and^ 
status restore; default. The blank-tag form also sets the standard default of no rotation. The 
defauh can be changed using rotate followed by status save; default. 

The effect of the graphic tranformation commands, including rotate, can be temporarily 
5 suspended with enable absolute and restored with disable absolute. 

The display control commands are applied in the following order: 

scale 
rotate 

aspect ratio correction 

10 origin 

window relative coordinates 
window clipping 

The following objects are not subject to rotation: 

text 

15 images 
windows 

boxes and erases specified using characters and lines (e.g., box 10,3) 

To rotate text, see the text rotate command. 
Example 

20 A box is continuously rotated at the center of the screen. 

define local 
degree ,2 
define end 
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origin zdispx/2 , 2dispy/2 $$ middle of the screen ^ 

mode xor 

loop 

rotate degree 

box -50,-50/ 50,50 ;1 $$ plot box 

delay 01 

box -50,-50; 50,50 ;1 $$ erase box 

calc degree c= degree +1 

endloop 

System Variables 

zrotate Number of degrees of rotation, 

zrotatex The X coordinate of the rotation origin, 
zrotatey The Y coordinate of the rotation origin. 

scale 

Scales graphic objects, 
scale [ factor I Xfactor, Yfactor [ LOCATION]] 
Description 

Causes all subsequently plotted graphic objects to be scaled by the given factor or 
separate x (horizontal) and y (vertical) factors may be specified. For example, scale .5 would 
make all graphics objects 1/2 size, while scale 2,3 would double graphics in the x direction, and 
triple them in the y direction. Scaling occurs relative to the plotting origin, as specified by the 
'Origin command, unless an optional scaling origin location is specified. 

Specifying a scaling origin affects only subsequently scaled objects. 
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The standard default is scale 1 (no scaling), set at each main unit and by initial ancTstatus 
restore; default. The blank-tag form also sets the standard default of no scaling. This default can 
be changed with status save; default. 

The effect of the graphic transform commands, including scale, can be temporarily 
5 suspended with enable absolute and restored with the disable absolute. 

The display graphic transform are applied in the following order: 

scale 
rotate 

aspect ratio correction 

10 origin 

window relative coordinates 
window clipping 

The following objects are not subject to scaling: 

text 

15 images 
windows 

boxes and erases specified using characters and lines (e.g., box 10,3) 
Example 

Produces a series of concentric boxes. 

20 define local 
factor, 2 
define end 



25 



origin zdispx/2 , 2dispy/2 
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loop . factor c: 1,10 
scale factor 
box -10,-10;iO,10;l 

endloop 

"System Variables 

zscalex The horizontal scaling factor ( 8-byte real) 

zscaley The vertical scaling factor (8-byte real) 

zscaleox x-coordinate of the scaling origin 
zscaleoy y-coordinate of the scaling origin 



10 screen 



Sets or tests screen resolution type. 



15 



20 



25 



35 



screen 
screen 
screen 



mode 



resolution 



chrome 



test: 

ative: 
edit: 



[ test,] type [.mode ] [.resolution ] [.chrome ] 
[ test,] variable, type, mode, resolution, chrome 
native I edit 

type keywords and values: 

cga 0 

ega 3 

vga 10 

mega 1 1 

evga 1 

keywords and values 
graphics 0 
text 1 

keywords and values 

low 0 

medium 1 

high 2 

altl 3 

altZ 4 

alt3 5 

keywords and values: 
color 0 
mono 1 

Only check if specified settings work and return result in zreturn, don't 
actually change settings. 

Set screen to highest possible settings (up to vga) for given display driver. 
Put settings to editor's settings. 



variable: Use numeric values instead of keywords for type, mode, resolution, and chrome. 
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Description 

Sets the screen hardware to the specified type, mode, resolution, and chrome. The choice 
of a screen setting is limited by the display driver, display controller and the monitor being used. 
In producing courseware that is to run on a wide variety of BM PCs directly using the DOS 
5 software platform, one needs to select a screen setting that is compatible with the lowest common 
display hardware. 

Normally, the screen command occurs once at the beginning of a lesson as in the +initial 
control block. 

When a screen command changes screen settings, the screen is erased, the display page is 
10 reset to 1, and all plotting parameters are reset to standard as if the following statements are 
executed: 

status restore; standard 
status save; default 

Shorthand Notation 

1 5 The most popular screen settings can be selected without inputting all arguments. 

Graphics and color are the default settings. The resolution usually defaults to the standard value 
for the display controller type. 



Shorthand 1 


Fully Specified Form 


^rxeen cea 


csa, 2raphics,medium,color 


screen, cea,hi2h,mono 


c?a,graphics,hi£ih,mono 


screen, ega 


e?a ?raphics,hi2h,color 


screen e^a^medium 


esa sraphics,medium,color 


screen esajow 


e^a, sraphics,low,color 


screen v^a 


v?a,sraphics,medium,coIor 


screen mce;a 


mcea araphics, medium, color 


screen mcea,hi2h,mono 


mcaa,graphics,hish,mono 


screen evga 


evea,sraphics,hi.s;h,color 


screen evea,medium 


evea,sraphics.medium. color 
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RETURN A MCMP GENERIC 
STATUS REPORT INDICATING 
SUCCESS. 



*) THIS IS THE MODULE THAT HANDLES E-MAILING THE 
SUBMISSION. RECORDING IT IN A DATABASE. WRITING IT 
TO A FILE, OR PERFORMING ANY OTHER NECESSARY 
SERVER-SIDE TASK WITH THE DATA.. 
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PASS THE PACKET THROUGH 
TO A MODULE THAT HANDLES 
THE FINAL DATA COLLECTION.*) 
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WAS THE^ 
YES / FAILURE T0^,,_ 
"^OCESS THE REQUES1 
DUE TO A POSSIBLY 
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:;ONDITION, 
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RETURN A MCMP GENERIC 
STATUS REPORT DESCRIBING 
THE ERROR. 
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RFTURN A MCMP GENERIC 
status' report DESCRIBING 

THE CONDITION AND 
INDICATING THE POSSIBILITY 
OF A DELAY IN PROCESSING 
THE DATA. 



U 



ADD THE PACKET 
THE UDSCP 
SUBMISSION 
PROCESSING QUEUE 
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GENERIC STATUS 
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AN UNKNOWN 
PACKET TYPE. 
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computer over said ne^vork link, the transmitted code modules being less than all of the code 
modules of said applications program; and 

operating said second computer to follow programming instructions in the transmitted 
code modules to assist said first computer in executing its work load. 



B^SDOCID <W0 99^37007A2 1 > 



wo 99/07007 



PCT/US98/15627 



418 

packets and receiving of responses to said echo packets from the respective servers, and (III) 
updating the response times in said list in accordance with the measured delays, 

34. The computing system defined in claim 30, further comprising a software modified 
circuit operatively connected to said code module exchange means for encrypting 
communications transmitted to said remote computer and for decrypting communications 
received from said remote computer. 

35. The computing system defined in claim 30 wherein said machine-executable code 
modules are written in a user-friendly programming code, further comprising an interpreter for 
translating said programming code into machine code directly utilizable by said processing 
circuitry. 

36. A method for distributing processing among computers on a computer network, 
comprising: 

storing an applications program in a nonvolatile memory of a first computer, said 
applications program being stored as a plurality of individual and independent machine- 
executable code modules; 

executing portions of said applications program on said first computer; 

transmitting a request over a network link from said first computer to a second computer 
not running at full capacity, said request being to take over the work load of said first computer; 

in response to a request from said second computer, selectively transmitting machine- 
executable code modules of said applications program from said first computer to said second 
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digital processing circuiir>' operatively connected to said memory for executing at least 
one of said machine-executable code modules; 

a communications link for communicating data and programs over a network to a 

remote computer; and 

a code module exchange means operatively connected to said memory and to said 
communications link for communicating with a remote computer via a network link to obtain 
from said remote computer a further machine-executable code module of said applications 
program, said digital processing circuitry being operatively tied to said code module exchange 
means for executing said further machine-executable code module upon reception thereof from 
said remote computer. 

31. The computing system defined in claim 30 wherein said computing system is a user 
computer on said network and said remote computer is a server computer. 

32. The computing system defined in claim 3 1 wherein said memory contains a list of 
servers on said network, said list including response times for the respective ser\-ers, further 
comprising server selection means operatively connected to said memory and said code module 
exchange means for instructing said code module exchange means to communicate with a 
server selected from among said secondary servers as having a shortest response time, said 
remote computer being the selected server. 

33. The computing system defined in claim 32,' further comprising updating means 
operatively connected to said memory and said communications link for (I) periodically 
sending echo packets to said sewers, (II) measuring delays between the sending of said echo 
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code module from among said machine-executable code modules from said first computer to 
said second computer. 

27. The computing system defined in claim 26 wherein said first computer is a primary 
server and said second computer is a secondary server on said network, said first computer 
including detection means for detecting an overload condition of said first computer, said first 
computer further including shunting means operatively connected to said detection means and 
the communications link at said first computer for shunting an incoming user request to said 
second computer when said overload condition exists at a time of arrival of said user request. 

28. The computing system defined in claim 27 wherein said first computer fiinher 
includes updating means operatively connected to said memory and said communications link 
for (I) periodically sending echo packets to a plurality of secondary servers on said network, 
(II) measuring delays between the sending of said echo packets and a receiving of responses to 
said echo packets from the respective secondary servers, and (III) updating the response times 
in a list in said memory in accordance with the measured delays. 

29. The computing system defined in claim 26 wherein said first computer is a server 
computer and said second computer is a user computer. 

30. A computing system comprising: 

a memory storing a portion of an applications program, said applications program 
comprising a plurality of individual and independent machine-executable code modules, only 
some of said machine-executable code modules being stored in said memory; 
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communications link and said comparison means for decrv'pting said encryption packet prior to 
tlie comparing of said user authentification code in said request with said list of user 
authentification codes in said memory. 

24. The computing system defined in claim 16, airther comprising means for 
determining whether a requested code module has an updated version and for responding to 
said request with an invitation to said remote computer to accept the updated version of the 
requested code module. 

25. The computing system defined in claim 1 wherein said machine-executable code 
modules are written in a user-friendly programming code, further comprising an interpreter for 
translating said programming code into machine code directly utilizable by said processing 
circuitry. 

26. A computing system comprising: 
a first computer; 

a second computer remotely located relative to said first computer; 
communications links at said first computer and said second computer for tying said 
first computer and said second computer to one another over a network, 

said first computer including a nonvolatile memory storing at least a portion of an 
applications program, said applications program including a plurality of individual and 
■ independent machine-executable code modules, 

each of the computers being provided with code module exchange means for 
cooperating with the code module exchange means of the other computer to transfer a single 
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request. 

19. The computing system defined in claim 1 8 wherein the secondary server to which 
said user request is shunted is said remote computer, said single code module being required 
for enabling said remote computer to process the user request. 

20. The computing system defined in claim 18, further comprising updating means 
operatively connected to said memory and said communications link for (I) periodically 
sending echo packets to said secondary servers, (II) measuring delays between the sending of 
said echo packets and a receiving of responses to said echo packets from the respective 
secondary servers, and (III) updating the response times in said list in accordance with the 
measured delays. 

21. The computing system defined in claim 1 7 wherein said network is the Internet. 

22. The computing system defined in claim 16 wherein said memory contains a stored 
list of user authentification codes, further comprising comparison means for comparing a user 
authentification code in said request with said list of user authentification codes in said memory 
and for preventing code-module retrieval and transmission in the event that the user 
authentification code in said request fails to correspond to any user authentification code in 
said list. 

23. The computing system defined in claim 22 wherein said request from said remote 
computer is contained in an encryption packet, further comprising means connected to said 
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16. A computing system comprising: 
digital processing circuitry; 

a nonvolatile memory storing general operations programming and an applications 
program, said applications program including a plurality of individual and independent 
machine-executable code modules, said memory being connected to said processing circuitry 
to enable access to said memory by said processing circuitry; 

a communications link for communicating data and programs over a network to a 

remote computer; and 

a code module exchange means operatively connected to said memory and to said 
communications link for retrieving a single code module from among said machine-executable 
code modules and transferring said single code module to said remote computer in response to 
a request for said single code module from said remote computer. 

17. The computing system defined in claim 16 wherein said computing system is a 
server computer on said network. 

18. The computing system define in claim 17 wherein said memory contains a list of 
secondary servers on said network, said list including response times for the respective 
secondary servers, ftirther comprising: 

detection means for detecting an overioad condition of the computing system; and 
server selection means operatively connected to said detection means, said memory and 
said communications link for determining which of said secondary servers has a shonest 
response time and for shunting an incoming user request to the secondary sender with the 
shortest response time when said overioad condition exists at a time of arrival of said user 
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a machine-executable code module by said first computer, whereby said first computer and said 
second computer engage in interactive processing via said network. 

12. The method defined in claim 8 wherein said machine-executable code modules are 
written in a user-fi-iendly programming code, fiinher comprising translating said selected one 
of said code module at said second computer from said programming code into machine code 
utilizable by said second computer. 

13. The method defined in claim 8 wherein said machine-executable code modules each 
incorporate an author identification, further comprising, in response to an instruction received 
by said first computer over said network and prior to executing said one of said machine- 
executable code modules on said first computer, determining whether the particular author 
identification incorporated in said one of said machine-executable code modules is an allowed 
identification and proceeding with the executing of said one of said machine-executable code 
modules only if said particular author identification is an allowable identification. 

14. The method defined in claim 8 wherein the storing of said portion of said 
applications program in said first computer includes caching said code modules in a nonvolatile 
memory of said first computer. 

15. The method defined in claim 8, further comprising transmitting a request fi*om said 
first computer to said second computer for a machine-executable code module during an idle 
time on said first computer. 
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9, The method defined in claim 8, funher comprising: 

sending a request 'from the first computer to a further computer for a list of servers on 
said network; 

after transmission of said list of servers from said further computer to said first 
computer, determining response times for said servers by (a) sending echo packets from said 
first computer to said servers and (b) measuring, at said first computer, delays between the 
sending of said echo packets and a receiving of responses to said echo packets firom the 

respective servers; and 

selecting said second computer from among said servers as the server having the 
shortest response time, the transmitting of said request for said further machine-executable 
code module being executed after the selecting of said second computer. 

10. The method defined in claim 8 wherein said request from said first computer is a 
second request directed to said second computer from said first computer, further comprising 
transmitting a first request from said first computer to said second computer via said network, 
said first request being for a first version of a particular machine-executable code module of 
said applications program, said second request being transmitted in response to a signal from 
said second computer indicating that a more recent version of said particular machine- 
executable code module is available, said second request being for said more recent version of 
said particular machine-executable code module. 

1 1 . The method defined in claim 8 wherein said second computer stores at least some 
of said machine-executable code modules of said applications program, said second computer 
executing at least one of said machine-executable code modules in response to the execution of 
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code module included in said machine-executable code modules; 

transmitting, from said first computer to said second computer via said network link, a 
signal indicating that a more recent version of said particular code module is available, said 
selected one of said machine-executable code modules being said more recent version of said 
panicular code module. 

7. The method defined in claim 1 wherein said machine-executable code modules are 
written in a user-friendly programming code, fijrther comprising translating said selected one 
of said code module at said second computer from said programming code into machine code 
directly utilizable by said second computer. 

8. A method for optimally controlling storage and transfer of computer programs 
between computers on a network to facilitate interactive program usage, comprising: 

storing a portion of an applications program in a first computer, said applications 
program comprising a plurality of individual and independent machine-executable code 
modules, only some of said machine-executable code modules being stored in said first 
computer; 

executing at least one of said machine-executable code modules on said first computer; 

transmitting, to a second computer via a network link, a request for a fiarther machine- 
executable code module of said applications program; 

receiving said further machine-executable code module at said first computer firom said 
second computer over said network link; and 

executing said fiarther machine-executable code module on said first computer. 
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packets from said first computer to said secondary ser^-ers and (b) measuring, at said first 
computer, delays between the sending of said echo packets and a receiving of responses to said 
echo packets from the respective secondary servers; and 

selecting said second computer from among said secondary servers as the secondary 
server having the shortest response time. 

4. The method defined in claim 1, further comprising: 
storing a list of user authentification codes in said memory; 

upon receiving said request from said second computer, comparing a user 
authentification code in said request with said list of user authentification codes in said 
memory; 

proceeding with the retrieving and transmitting of said selected one of said machine- 
executable code modules only if the user authentification code in said request matches a user 
authentification code in said list. 

5. The method defined in claim 4 wherein said request from said second computer is 
contained in an encryption packet, further comprising decrypting said encryption packet prior 
to the comparing of said user authentification code in said request with said list of user 
authentification codes in said memory. 

6. The method defined in claim 1 wherein said request from said second computer is a 
' second request directed to said first computer from said second computer, further comprising: 

receiving a first request directed to said first computer from said second computer via 
said network link, said first request asking for transmission of a first version of a particular 
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WTIAT IS CL.M.VED IS: 

1 . A method for optimally comrolling storage and transfer of computer programs 
between computers on a network to facilitate interactive program usage, comprising: 

storing an applications program in a nonvolatile memory of a first computer, said 
applications program being stored as a plurality of individual and independent machine- 
executable code modules; 

in response to a request from a second computer transmitted over a network link, 
retrieving a selected one of said machine-executable code modules and only said selected one 
of said machine-executable code modules from said memory; and 

transmitting said selected one of said machine-executable code modules over said 
network link to said second computer. 

2. The method defined in claim 1 wherein said first computer is a server computer on a 
network, said second computer being a secondary server on said network, funher comprising, 
in response to a user request directed to said first computer, forwarding said user request from 
said first computer to said second computer to initiate processing of said user request by said 
second computer, said selected one of said machine-executable code modules being required 
by said second computer to process said user request. 

3. The method defined in claim 2, further comprising: 

storing, in a memory of said first computer, a list of secondary servers on said network, 
said list including response times for the respective secondary servers; 

periodically updating said response times, said updating including (a) sending echo 
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.^though the invention has been described in terms of particular embodiments and 
applications, one of ordinary- skill in the art. in light of this teaching, can generate additional 
embodiments and modifications without departing from the spirit of or exceeding the scope of 
the claimed invention. Accordingly, it is to be understood that the drawings and descriptions 
5 herein are proffered by way of example to facilitate comprehension of the invemion and should 
not be construed to limit the scope thereof 
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zero 

Zeroes a variable or a specified number of bytes, 
zero variable [ ,lengtii ] 
Description 

5 Zeroes bytes of variable space. The one-tag form zeroes only the variable specified. The 

two-tag form zeroes any number of bytes, beginning at the specified variable ; variable 
boundaries can be crossed with this form. 
Example 

To zero a large variable with one command. 

10 define global 

var, 128 $$ a 128-byte buffer 

define end 

* 

zero var SS zero all 128 bytes] 
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colon : ^ 

comma 

end-of-line J 
universal delimiter | 
Examples 
Example 1 

The variable month is used to selectively pick the text for displaying a month. The first 
two cases (negative and zero) are not used for text. 

write Today's month is $$$ retain the trailing space 

writec month, , , January , February , March , April , May , June , 
July , August , September , October , November , December 

Example 2 

Multiple lines of text can occur in each selective case. Delimiters not used as the selector 
delimiter can occur in the text. 

writec question; ; ; 

What city was once called Fort Dearborn? 

Hint: it is also called the Windy City.; $$ case 1 

What is the largest city in the US? 

Hint: it is on the east coast.; $$ case 2 

What city is known as the Gateway to the West? 



Hint: it is on the Mississippi.; 



$$ case 3 
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Example 2 ^ 

Embedded show commands can display both text and numbers from variables. The 
following would display something like; 

Bill: 

5 your score is 92% 

the class average was 85%. 

write «showa, naine»: 

your score is «show, score»% 

the class average was «show , average»% . 

10 Examples 

write Special effects such as underlining and italics are easily 

put on characters through insertion of embedded code sequences 
in the editors. Some attributes such as size can use the 
embedded command form so that they «size,4» can be seen clearly 
15 in «color, red+» printouts of your code. wri tec 

writec 

Selectively display text, 
writec SELECTOR; TEXT, TEXT;... 
Description 

20 The selective form of the write command. 

The delimiter first following the SELECTOR is used to separate all following TOT cases 
-andean be a: 

semicolon : 
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text start" uncover code sequence Esc-&, A writex variant of this command does not sav»4he 
starting text attributes: it restores attributes to tliose saved by the previous write command. 

The display of the contents of variables and buffers can also be embedded in the text of a 
write by using the embedded form of show commands: 
5 show 1 s displays a variable or expression 

showa 1 a displays text in a buffer 

showh I h displays a buffer in hexadecimal format 

showt 1 t displays a variable in tabular format 

showv 1 V displays a text buffer including null codes 

10 Trailing spaces on a line of text are normally stripped ofFby the compiler: they can be 

included by ending the line with a triple dollar sign comment (SSS). 
Examples 
Example 1 

The following write goes on for three lines in source code. However, it will be displayed 
1 5 for many more lines on the screen since the margins as set by the at command make for a very 

narrow paragraph. 

at 1:10; 10:30 ^^^^ margin is char 10 

$$ right margin is char 30 
text margin; wordwrap $$ wrap full words at right margin 

20 write This is a paragraph of text that goes on and on. It will 

appear nicely between the margins as set by the preceding at 
command. Continued lines of text in a write statement begin by 
tabbing over the command field. 
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write 

Displays text. 



write TEXT 



Description 

5 Displays text on the screen beginning at the current screen location. The location is 

usually set by a preceding at command which can also set left and right text margins. The text of 
the write can extend for many lines whose wraparound behavior is controlled by the text margin 
command. 

Text attributes (e.g., color, underline, drop shadow, font design, etc.) can be changed 
10 character-by-character through use of embedded text attributes. These can occur in the text as: 
uncover code sequences that are inserted through menu options in the source code and display 
editors; and embedded commands that are included through use of the embed symbols « ». Over 
50 text attribute uncover codes exits . The commands and text command keywords that can 
embed attributes are: 
15 color 1 c selects foreground display color 

colore I ce selects background display color 
margin | ma controls text wrapping 
mode I m selects how text plots over existing displays 

size I s changes size of fonts 

20 spacing | sp selects proportional or fixed spacing 

The text attributes that exist at the start of a write are saved and restored at the end of the 
write so that any attribute changes made within the text do not extend to following commands. 
These starting saved attributes can be restored to at any time within the text by use of the "status 
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is saved in the memory pool When window compression is set on, the saved data occupier 
considerably less memory pool space; when compression is set off, more space is used in the 
memory pool but on older model computers the window may open and close more quickly. 

System Variables 

zreturn 

.] Operation successful 

Ig Insufficient memory in memory pool 

23 Part of window off physical screen 

Miscellaneous 

The following system variables are affected by window 



15 



20 



zdispx 

zdispy 

zxmax 

zymax 

zwindowx 

zwindowy 

zclipxl 

zclipyl 

zclipxl 

zclipy2 



width and height of window 



maximum x- and y-coordinates in window 



absolute x- and y-coordinates of lower left window corner 



absolute x- and y-coordinates of lower left clipping area 



absolute x- and y-coordinates of upper right cHpping area 
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window frame [; LOCATION [; LOCATION ]] 

Changes the boundaries of the current display window. The contents of the window and 
the saved display under the window are not changed, window frame can be used on the outer- 
level physical screen window. 
5 window frameabs [; LOCATION [; LOCATION ]] 

Identical to window frame except that the rectangular location is interpreted as though 
enable absolute is in effect: coordinates refer to the physical screen. A previously opened 
window or the origin command have no effect, 
window relative; (on I ofT | CONDITION ] 
1 0 Turns on or off the use of window-relative coordinates for the current display window. 

The default when a window is opened is relative on. If relative coordinates are turned off, then 
coordinates are relative to the physical screen rather than the current window; however, scale, 
rotate, origin and window clipping still apply. 

For the CONDITIONAL form, an expression that evaluates to a negative value is treated 
15 as on while zero or a positive value is treated as off. 
window clip; [ on | off | CONDITION ] 

Turns on or off the clipping of display objects that extend outside the current window. 
The default when a window is opened is clip on. If clipping is turned off, objects extending 
outside the current window will be displayed. 
20 The system variables zclipxl, zclipyl, zclipx2, zclipyZ hold the absolute coordinates for 

the lower left and upper right of the clipping area, 
window compress; [ on I off I CONDITION 1 

Controls data compression of the underlying screen. The default when a window is 
opened is compress on. When a window is opened, the contents of the display under the window 
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Press any key to continue. . . 
pause pass=all 
window close 

5 Example 2 

at 5:15 
window open; 20,5 

A window 20 characters wide and 5 lines deep is opened at the underlying screen (or 
window) location of line 5 character 15. 
10 window openabs [; LOCATION [; LOCATION ]) 

Identical to window open except that the rectangular location is interpreted as though 
enable absolute is in effect: the lOC^ T/OA^ coordinates refer to the physical screen and are not 
affected by any previously open window or the origin command, 
window close [; noplot ) 1; noarea 1 
15 Closes the current display window, restoring from the memory pool the saved display 

beneath the window, the display status, the area definitions, and the status of window relative, 
window clip, and window compress. The optional keyword noplot inhibits the restoration of 
the display beneath the window. The optional keyword noarea inhibits the restoration of area 
defines. 

20 window reset [; nopiot] [; noarea] 

Closes all open windows in order from the last to the first opened, restoring the display 
beneath the window, the display status, the area definitions, and the status of window relative, 
window clip, and window compress. The optional keyword noplot inhibits the restoration of 
the display beneath the window. The optional keyword noarea inhibits the restoration of area 

25 defines. 
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the first character on the top line in the window. Display objects are clipped if they extend'Beyond 
the window (see window clip). 

The rectangular coordinates for window are affected by any previously opened window 
and the origin command; they are not affected by scale, rotate, or window clip. Use window 
5 openabs or enable absolute to locate a window relative to the physical screen without regard to 
any previously opened window. A window is not opened if it would extend oflF the physical 
screen (zreturn = 23). 

When both rectangle LOCATIONS are blank, the entire screen or previous window is 
impjied. When only one rectangle LOCATION {\ht first) is present, it denotes that the current 
10 screen location should be used for the starting position and LOCA TION givQs the number of 
characters or characters and lines of the currently selected font to size the window by. 
Example 1 

A window opens on a VGA screen with a blue background, white border, and some text. 
When any key is pressed, the window is closed and the underlying display is restored. 

15 window open; 100,100; 400,250 $$ open window, middle offscreen 
colore blue 

erase $$ clear window to blue 



20 



color white+ 

box ;;1 $$ put border around window edge 

at 2 : 4 

write The author of this lesson is: 



25 Dr. John Burdeen 

University of Illinois at Urbana 
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close closes current window, restores previous display status " 

reset closes all windows, restores previous display status 

frame changes window boundaries using relative coordinates 

frameabs like frame except uses absolute coordinates 

5 relative controls use of window-relative coordinates 

clip controls clipping of graphics extending beyond window 

compress controls compression of saved underlying display 

Description 

The window command opens, closes, and alters display windows. When a window is 
10- opened, the current display status and screen display under the window is saved in the memory 
pool. Further display operations are relative to and appear only in the window unless the absolute 
coordinates feature is selected. When a window is closed, the previous display status and screen 
display under the window is restored. 

On entry to the system, an initial window is opened that corresponds to the entire physical 
15 screen. Properties of this outer-level window can be altered with the window command but it 
caxmot be closed. 

window open [; LOCATION [; LOCATION ]] 

Opens a display window over the rectangular area specified, saving in the memory pool 
the screen display underneath the rectangle, the display status (see status), the current area 
20 settings (see area), and the current setting for relative coordinates (window relative), clipping 
(window clip) and compression (window compress). Upon closing the window, the saved data 
are used to restore the screen to its previous state. 

Screen coordinates are relative to the newly opened display window: the graphic 
coordinate 0,0 is at the lower left corner of the window and the character coordinate 1:1 refers to 
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Width 

Description 

Specifies a width for graphics; default is one pixel System variable zwidth holds the 
current width value. Width is added symmetrically on both sides of the basic graphic elements 
5 except for dot which just grows larger. 

The following commands are affected: 
dot 
draw 

polygon (non-filled only) 

1 0 circle (non-filled only) 

ellipse (non-filled only) 

box and erase are not directly affected by the width command. However, they can use the 
system variable zwidth for their width argument and thereby become connected. Note that these 
graphics only "widen" inwardly due to their pre-existing width argument definition. 
1 5 The current width setting is part of the status buffer 

width expression 

width 5 $$ following line graphics 5 pixels thick 

width var $$ width depends on variable 

window 

20 Manages display windows. 

window keyword... 

open opens display window using relative coordinates 
openabs like open except uses absolute coordinates 
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nnHprltn^ color 


4 1 


current underline color 


( rp<;f*rv'pci^ 


6 




UviciY ultarv 


I 


-1 = ves; 0= no 


lUai tLlil 


1 


-I = advance; 0= wrap; I = release; 2= wordwrap 


Ull CUllUU 


2 


0 = riuht; 90 = up; 1 80 = left; 270 = down 


I UlallUU 


2 


0..359 




1 


• 1 = baseline; 0= bottom 


delay 


4,real 


delav in seconds 


reveal 


1 


0 = off; 1 = reveal* ; 2 = all; 3 =allcr; 4= editor 


X increment 


2 - 


X - increment 


y increment 


2 


v - increment 



* for the obsolete reveal on command. 



Example 

Reads the current text attribute settings and displays them. 

define local 
5 settings, 54 

sizcx,2 
sizey,2 
bold,l 

10 define end 
* 

text info; settings 

write The current X-size «s, sizex» 
Y-size «s, sizey)> 

15 and bold is 

writec bold; on; off 
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off (0) return to functioning hidden codes 

text measure 

Initializes the text measuring system variables that can be used to determine the 
rectangular extent of a paragraph of text. The system variables define the corners of a rectangle: 
5 (zplotxU zplotyl) ; (zplotxh, zplotyh) 

Example 

A paragraph of any width and height is framed. Muhiple write and show commands can 
occur where the example uses a single write. 

tttx^ measure 
10 write This is a paragraph 
o£ text. . . 

box zplotxl , zplotyl ; zplotxh, zplotyh ; 2 

text info; infoBuffer {length] 

Reads information on the current settings of the text options into a buffer for the given 
15 length. If the length is not specified, the defmed length of the buffer is used. The format of the 
buffer is: 



Text Option 


Bvtcs 


Possible Values 


sizex 


2 


1...9 


size V 


2 


1...9 


bold 


1 


-1 =on;0 = off 


italic 


1 


-1 =on:0 = off 


narrow 


1 


-1 = on; 0 = off 


(reserved) 


5 




blink 


1 


-1 - on; 0= off (text.obsolete) 


brieht 


1 


-1 = on; 0= off (text,obsolele) 


y base same 


1 


-1 = on; 0 = off (charsets, obsolete) 


soacins 


1 


-1 = variable; 0= fixed 


shadow 


1 


-1 =on;0 = off 


shadow color 


4 


current shadow color 


(reserved) 


5 




underline 


1 


-1 =on; 0= off 


underline 


1 


-I = forcHnd: 0= soecific color 
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When bottom alignment is in effect, characters align along the bottoms of their character 
cells. When several sizes or styles of characters are lined up by their bottoms, they don't appear to 
be on a common line due to the need for the descender part to grow with the size of the character 

.vvV vervfunny 

5 When baseline alignment is in effect, the baseline in the standard font is used to 

determine the placement of characters from all other fonts on the screen. In the standard size 1 
font, the baseline is located zcharb above the bottom of the character cell. For the currently 
selected font and size enlargement, the baseline is located zfontb above the bottom of the cell 
Since the baselines are to hne up, the current font is plotted with the bottom of its cell located 

10 zcharb-zfontb vertical dots from the set zy location where the standard font size 1 bottom 
plots. 

The variable tag from uses the values: -1 = baseline, 0 = bottom 
text reveal; ofT 1 all I allcr | editor | reveal 

Controls display of hidden text codes; the default is off. 
1 5 Displays rather than functions the hidden codes occurring in text such as uncover escape 

codes, superscripts, subscripts and the carriage return (CR). The hidden code display is either a 
sinde symbol or begins with a square followed by one to three additional characters specifying 
the hidden function.. The variable tag form use the values shown after the keywords, 
ail (2) displays hidden codes except CR; CR functions 

20 ■ allcr (3) displays hidden codes and CR; CR functions 

editor (4) displays hidden codes and CR; CR does not function 
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starting point of the text around the screen with each iteration of the loop. The text in the write 
statement starts with a space which in mode rewrite removes the starting part of the underlying 
"W" from the previous iteration. If the example is changed to move to the left, the text should 
have the trailing space at the end. 
5 zero X 

text margin; wrap $$ turn on screen wrap-around 

text size; 2 

mode rewrite $$ replace screen underneath 

flow jump; %other; start; break $$ provide exit on any key 

10 loop 

calcs x = zxmax; x c= 0 ; x+1 

at X, zymax/2 $$ half-way up screen 

write Welcome to AVIATION BASICS $$note first space 

endloop 

15 text align; baseline | bottom 1 align 

Aligns characters of different sizes or fonts; the default is baseline. 
The align options control how characters of different sizes or fonts plot relative to each 
other. This is done by lining them up either on their baselines or the bottoms of the character cell. 
The baseline is usually the bottom point of letters without descenders and is set in the Font Editor 
20 for each font. 

When baseline alignment is in effect, characters align along their baseline. Different sizes 
and styles of fonts appear to be on the same line: 
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editing write objects in the Display Editor. Several special characters such as hard-space anff 
hard-hyphen exist for use in wordwrap mode. 

The wrap option causes characters and parts thereof that extend past the edge of the 
window or screen to wrap around to the opposite side of the screen and continue plotting: any 
5 margins set by at are ignored. The wrap occurs even within a character so that pieces of it may 
appear on both sides of the screen or window. A billboard effect can be given to animated text 
that wraps around the screen. 

The release option allows character plotting to continue or start outside the window or 
screen: any margins set by at are ignored. No advance is done. If the standard clipping is in 
10 effect, only the characters and parts thereof that exist in the window appear. 

The variable tag form uses the values: -1 = advance, 0 = wrap, 1 = release, 2 = wordwrap. 

Example 1 

This paragraph of text 
looks just like this when 
1 5 plotted in wordwrap mode 
by the following code. 

screen vga 

text margin; wordwrap 

at 0,464;204, 0 

20 write This paragraph of text looks just like this when plotted in wordwrap 

mode by the following code. 

Example 2 

The code below causes the text Welcome to Aviation Basics to cycle around the screen 
from left to right as if on a billboard. The calcs statement tests for the screen right edge and either 
25 advances the variable x by one or resets it to 0. The following at statement then advances the 
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The character grid is not rotated unless done by a previous text rotate statement, 
The direction that characters will be displayed is specified by keywords (or variable 

value): 

right (0) from left to right 

5 left (180) from right to left 

up " (90) from bottom to top 

down (270) from top to bottom 

With direction set to left, various leftward plotting languages such as Arabic and Hebrew 
can be displayed when using the proper font. 
10 Example 

text direction; left 

text delay; . 1 

write drawtfei gniog 

Causes the phrase going leftward to slowly appear on the screen starting from its right 

15 end. 

text margin; advance | release | wrap j wordwrap | margin 

Controls the behavior of text going past the right margin or the edge of the screen or 
window; the default is to advance character plotting to the next line. 

The advance option is the default for displaying lines of text. It pre-checks whether any 
20 part of a character would plot past the right margin or edge of the window or screen and if so 
advances the character to the left margin on the next line. 

The wordwrap option pre-checks whether any part of a word would plot past the right 
margin or edge of the window or screen and if so "wordwraps" the entire word to the left margin 
of the next line. This mode is commonly used for wordprocessing and can be accessed while 
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Example 

Causes each successive character to be plotted 2 pixels to the right and 3 pixels lower 
than its normal position. 

text increment; 2,-3 

5 write Descending text! 

text rotate; degrees 

Rotates the character plotting baseline in degrees; the default is 0. 
For best results, use rotations that are a multiple of 90 degrees on screens that have a 1: 1 
aspect ratio (generally type VGA or EVGA). 
10 Example 1 

Rotates the character plotting baseline by 90 degrees counter-clockwise so that the word 
TEMPERA TURE can be the label for the vertical axis of a graph. 

at 250,200 
text rotate; 90 

15 write TEMPERATURE 

Example 2 

Four copies of the alphabet appear rotated around the center of the screen. 

loop angle c= 0, 270, 90 

at zxmax/2, zyinax/2 
20 . text rotate; angle 

write ABCDEFGHIJKLMNOPQRSTUVWXYZ 

endloop 

text direction; right I left | up 1 down I direction 

Controls the direction that text will be displayed relative to the character plotting baseline; 
25 the default is right. 
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Example ^ 

Underlines the first sentence with the foreground color and the second sentence with blue. 
Using escape codes in the text is an alternate method for turning on underlining. 

text underline; on,foregnd 

5 write This text is underlined in the same color as the text, 

text underline; on, blue 

write This text is underlined in blue. 

text delay; seconds [; break] 

Delays for the specified time in seconds after plotting each character; the default is 0. 
10 Presence of the optional break modifier allows any break modified flow event to occur rapidly 
when a long delayed text statement is executing: the delay is temporarily turned off for the 
remainder of the output allowing the command to quickly complete so that the flow branch can 
occur. 

Example 

15 Causes the message to come on the screen slowly (a quarter second delay between each 

character). 

text delay; 0.25 

text size; 2 

color red+ 
20 v^rite WAHITIKG! 

text increment; x,y 

Adds an additional spacing offset after plotting a character; the default is 0,0. 
After plotting a character, the x offset is added to the horizontal location and the;^ offset 
is added to the vertical location. Negative offset values are allowed. 
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1512 

text shadow; on ! off I CONDITION [,COLOR ] 

Controls character drop shadowing; the default is off. The shadow color defaults to 

white, 

5 The shadow effect is produced by displaying each character twice: the first plotting is 

offset and in the shadow color while the second is in the foreground color. The drop shadow 
offset for a font is set in the Font Editor. If no shadow color is specified, the last specified color is 
used. The default shadow color is white after an initial command. 
Example 

1 0 Gives a very patriotic effect for an American display. 

colore blue 
erase 

color white+ 
text shadow ; on , red+ 

15 text size; 2 

at 10:10 

write An American statement. 

text underline; on I off 1 CONDITION [,COLOR | foregnd ] 

Controls character underlining, the default is ofT. The color of an underline defaults to the 
20 current foreground (keyword foregnd) color as used for plotting the character. 

The location of the underline and the size of the descender gap is specified for a font in 
the Font Editor. If no underhne color is specified, the last specified underline color is used. The 
default underline color is foregnd after an initial command. 
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With variable spacing, each character occupies only the horizontal space required. For 
example, the lower case / occupies less horizontal space than the upper case M Many more 
characters per line can be plotted with variable spacing than with fixed. Studies show that 
variable spacing increases reading speed. 
5 The variable tag form uses the values: - 1 = variable, 0= fixed. 

Example 1 

When used with the standard font, the second line of text with variable spacing takes up 
less space on the screen than the first line with fixed spacing. 

at 10:1 

10 text spacing; fixed 

write This text runs to here, 

at 11:1 

text spacing; variable. 

write This text runs to here plus. 

15 Example 2 

Variable spacing is used for the labels but fixed spacing solves the problem of lining up 
the numbers. 

at 6:10 

text spacing; variable 

20 write Pork 
Beef 
Chicken 
at 6:20 
text spacing ; fixed 

25 write 365 
4 
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* in ^initial block 

initial 

text bold; on 

text spacing; variable 

5 ... 

status save; default 

text italic; on 1 off 1 CONDITION 

Controls the italic attribute; the default is off. 
Example 

10 The escape codes for turning italic on and off have been inserted around the word 

amorous. In the Source Editor, these are input by pressing [CTRL] [A] [I ] and [CTRL] [A] 
[SHIFT] [1 ] The italics are either synthesized from the current font or, if a font group is active, 
come directly from the appropriate italic font in the group 

write The word amoxous is derived from Latin. 

15 text narrow; on ! off I CONDITION 

Controls narrow font usage from a font group; the default is off. 
The narrow attribute is of use for low resolution screens like the CGA in order to 
produce the maximum amount of text on a screen. Narrow fonts are supplied in the system 
standard font group to provide for upward compatibility with previous versions of the TenCORE 
20 system, narrow carmot be synthesized. 

text spacing; fixed I variable 1 spacing 

Controls character spacing; the default is fixed. 

With fixed spacing, each character occupies the same horizontal space defined as the 
maximum character width for a font. It is often used to align tables of numbers or to produce 
25 emphasis. 
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Example ^ 

A 4-by-4 matrix of X's appears showing the 16 sizes of character enlargement that 
can be synthesized for the two argument form of size, letters should be a font and not a font 
group otherwise the four sizeX = entries would attempt to match and use a group font 
5 that would not match in style the other synthesized sizes. 

font *letters» 
loop sizeX c= 1,4 

loop sizeY c=l,4 

at 4*sizeX+l: 4*si2eY+l 

10 . text size; sizeX,sizeY 

write X 

endloop 

endloop 

text bold; on | off I CONDITION 

15 Controls the bold attribute; the default is off. 

Example 1 

The font big is made bold by having each pixel in a character horizontally duplicated. 

font big' $$ a font block 

text bold; on 

20 write This text is synthesized bold. 

Example 2 

In the +initial control block, the initial command sets all the plotting parameters 
including the font to the system standard. Several text attributes are then changed and saved in 
the default status buffer. Any jump branch now resets to these default text attribute settings. 
25 ' Since the system standard font is a font group, the boTd attribute selects a bold font from this 
group. 



BNSDOCID' <W0 9907X7A2 I > 



wo 99/07007 PCTAJS98/15627 

383 

system variables zfontf and zfontret for more information on how fonts are selected from rfont 
group to best match the attribute settings, 
text size; size 

Controls the size attribute; the default is size I. 
5 For a font, up to a 4-time enlargement of the base size character is synthesized in both the 

horizontal and vertical dimensions. For a font group, the system attempts to select an 
appropriately sized font in the group up to a maximum size of 9. If the size doesn't exist as a font 
in the group, sizes up to 4 are synthesized while larger sizes default to 1 . 
Example 1 

10 If used with a font, character doubhng from the base font is synthesized. If used with a 

font group, the appropriate size 2 font in the group is used; if none exists, it is synthesized from 

the base size 1 font, 
text size; 2 

Example 2 

15 Size is one of the text attributes that can be embedded into a line of text by use of the « 

and » embed symbols. The embed method has advantages over escape codes in that the text is not 
altered for viewing in the Source Editor and makes for a better printout of the coding. 

write «size,l»Start out small, «si2e,2»end up big. 

text size; sizeX,sizeY 

20 Sizes the horizontal and vertical character enlargement independently up to the maximum 

size value of 4. For unequal X and Y values, the characters are always synthesized. For equal X 
and Y values, the characters either come from a matched font of an active font group or are 
synthesized. 
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cyan / cyan+ 


c/C 


red / red+ 


r/R 


magenta / magenta+ 


m/M 


brown / brown+ (yellow) 


b/B 


white / white+ 


w/W 


PLOTTING MODES 


Escape Code 


erase 




inverse 


I 


noplot 




rewrite 


= 


write 




xor 


* 


FONTS 


Escape Code 


font number 1 - 9 


f 1 -9 


font number 10-35 


fa-z 


font standard / text start 


f@/& 


FONT CONTROL 


Escape Code 


bold on / off 


Fb/B 


italics on / off 


Fi/I 


shadow on / off 


Fs/S 


shadow color 


F / color 


underline on / off 


Fu/U 


underline color 


F _ color 


FUNCTIONS 


Escape Code 


size 1 - 9 


1 - 9 


spacing variable / fixed 


v/ V 


narrow on / off 


n/N 


status default / text start 


@/& 


erase color 


d color 


magin wrap / release 


>/< 


margin advance / set left 


CR/1 


CHARACTER FUNCTIONS 


Escape Code 


non-breaking space 


u 

IT 


non-breaking hyphen 


h 


new line 


\ 


continued write 


1 



The size, bold, italic and narrow attributes either synthesize their effects starting with an 
individual font or select the best font match from a font group. See the font command and the 
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shadow 


controls drop shadowing 


5 


underline 


controls underlining 


6 


delay 


sets delay time between characters 


7 


increment 


adds extra spacing between characters 


7 


rotate 


rotates text baseline 


7 


direction 


controls plotting direction relative to baseline 


8 


margin 


controls text wraparound at margin 


9 


align 


controls alignment between fonts 


10 


reveal 


displays rather than functions uncover text codes 


12 


measure 


initializes text extent measurements 


12 


info 


returns text attribute information 


13 



Description 

Alters the way text appears on the screen. Text attributes are initialized to system defaults 
by the initial, screen or the status restore; standard commands. After selecting text attributes 
15 for a panicular lesson, the modified settings can be saved and later restored by the status 

command. If the modified settings are saved in the default status buffer (say, by programming in 
the +initial control block), they will become the staning text attributes for any unit branched to 
by a jump. 

While entering a line of text in the Source Editor, most of the text attributes can be 

20 manipulated directly in the text string through using uncover escape codes or the embedded 

command syntax. Following are the escape codes: 

COLORS Escape Code 

black / black+ (gray) a / A 

blue / blue+ u / U 

green / green-r g / G 
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status restore; mystat; delete ^ 

Status delete; 'NAiME' | local 

Deletes a saved status block from the memory pool. 
Example 

5 Deletes the pagel set of saved settings from the memory pool. 

status delete; »pagel' 

Status reset 

Deletes all named status blocks from the memory pool. The default, local, arrow, and 
standard buffers are unaffected. 
10 System Variable 

zreturn 



-1 Operation successful 

6 Duplicate name 

10 Name does not exist (no previous status save) 

15 16 Invalid name 

1 8 Insufficient memory in memory pool 



text 

Controls text attributes. 



text keyword... 

20 size selects sized fonts 2 

bold selects bold fonts 3 

italic selects italic fonts — 4 

narrow selects narrow fonts 4 

spacing controls character spacing 4 
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status restore; 'NAME* | local (; delete j ^ 
status restore; default | arrow 
status restore; standard 

Replaces the current plotting status with a previously saved set. If the palette was 
5 originally saved, it is restored. Optionally, the named or local block can be deleted from the 
memory pool by using the delete modifier 

The arrow option restores the status in effect when the last arrow command was 
encountered. The palette is not restored. 

The standard option restores the system standard plotting status, excluding the palette. 
10 To restore the standard palette use palette init. 
Example 1 

Restores the default plotting parameters (those last saved by a status save;default 
statement). 

status restore; default 

15 Example 2 

Saves and restores the plotting and palette settings over a library call The library routine 
can alter the display settings as desired without affecting the calling program upon return. 
Alternately, the status save and restore could be built into the library routine to provide a more 
easily used tool. 

20 status save; local; palette 
library routines , graph 
status restore ; local 

Examples 

Restores the settings whose name is contained in the variable mysiat The memory block 
25 is then deleted. 
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The memory pool is used by the commands: memory, image, window, status, are^, 
flow, font and perm. Memory blocks are tagged as belonging to a specific command type at 
creation and cannot be accessed by other commands using the memory pool; different commands 
can use the same name for a memory block without conflict. 
5 Example 1 

Plotting parameters are initialized in this ^initial control block then saved in the default 
status buffer. These settings become the defaults for all subsequent main units that are reached by 
a jump branch. The erase command is used to bring the screen to the blue background even for 
the first branch into this lesson. 

10 * in control block +initial 

initial 

color yellow 
colore blue 
size 2 
1 5 font geneva 

status save; default 
erase 

Example 2 

Saves the current plotting parameters and palette in the memory pool under the name 

20 status!. 

status save; 'statusl'; palette 
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bold; off ^ 
delay; 0 
direction; right 
increment; 0,0 
5 italic; off 

margin; wrap 
narrow; off 
reveal; off 
rotate; 0 

10 shadow; off, white 

size; 1 

spacing; fixed 
underline; ofF,foregnd 
• thick off 
15 status save; 'NAME' 1 local [; palette ] 
status save; default [; palette J 

Saves the current plotting status in a memory pool block or the default buffer. The name 
can be either a text literal or contained in a variable. Named blocks can be restored later in any 
unit The palette modifier causes the current palette settings to also be saved. 
20 The local keyword saves the status in a memory pool block specific to the current unit. A 

local block can be restored only in the unit which saved h; it is deleted automatically when 
execution of the unit ends. 

Saving the status to the default buffer makes it the default for all new main units entered 
by a jump branch. 
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376 

maintain the plotting parameters over a subroutine call, or to provide a common look to all*main 
units of a lesson by resetting the defaults. Restore options allow for the reinstatement of the 
system standard settings or the settings at the previous arrow in a unit, 
status saves and restores these items: 
• current screen location 



• margins (both left and right) 

• all loaded fonts, including current and standard fonts 

• palette (if requested) 

The settings of the following commands are also saved and restored by status. They are 
10 shown with their system standard settings that can be set to as a block with the status 
restore;standard option (or with the initial command), 
blink off 
color white 
colore black 
colorg black 
disable cursor 
enable font 
font standard; standard 

mode write 
origin 0,0 
rotate 0 
scale 1,1 
text align; baseline 
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After a showv, the current screen location is updated to the character position following 
the last character displayed. 
Example 

The showa plots "ABC" while the showv plots "AB C". 
5 define local 
var, 4 

define end 

calc var c= h41 42 00 43 $$ A B null C 

10 at 10:10 

showa var $$ ABC 

at 11:10 

showv var $$ ABC 

Status 

15 Saves and restores display status information. 



status keyword... 




save 


saves current display settings in memory block 


restore 


restores display settings from memory block 


delete 


deletes named status memory blocks 


20 reset 


deletes all status memory blocks 


Description 




Saves the state of the current plotting parameters (such as the foreground and erase 


colors, mode, font, etc.) in a memory pool block or the default buffer. The saved status can later 


be restored to bring all plotting parameters back to their previous state, status can be used to 
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write Anderson 

Carmen 

Engdahl 

Lillith 
5 at 8:18 

write «t , rate (1) , 5 ,2» 

«t,rate (2) ,5,2» 

«t,rate (3) ,5,2» 

«t , rate (4) ,5 ,2» 
10 at 8:31 

write $«t,rate(l) *2080,8,2» 

$«t,rate(2) *2080,8,2» 

$«t,rate(3) ♦2080, 8, 2» 

$«t,rate(4) *2080,8,2» 

15 showv 

Displays text bufTer including null codes. 



showv buffer [ , length ] 

write « showv I v , buffer [ , length ] » 



Description 

20 Displays the contents of a buffer as alphanumeric characters, including any null characters 

(hex value hOO) which are converted to space codes if they are actually plotted on the screen. 
Unlike showv, the showa command ignores null characters. 

showv is primarily used in its embedded form fn the tag of pack and put. In this case, 
showv causes null characters to be treated like any other character and does not ignore them or 

25 convert them to spaces. 



BNSDOCID- <W0. 9907007A2,I_> 



wo 99/07007 



PCT/US98/15627 



10 



373 

Default Values 

If the optional tags are omitted, the following default values are used: 



CF the variable 

is... 


Then defauU field and 
r/^/z/ are... 


1-4 byte integer 


8,0 


8 byte integers and 
reals 


12,3 



showt displays special symbols to indicate the following error conditions 



09*>0*>*> 



operation. 
Example 



The number to display does not fit in the specified field. 

The number is invalid. This is usually the result of an illegal floating point 



Displays some entries in a table. 

define local 

rate (4); 8, real $$ pay rates end 

define end 



calc 

15 

at 

write 
at 

20 write 
^ at 
8:30 



rate(l) c= 4 . 05 
rate (2) c= 12.76 
rate (3) <= 8.63 
rate(4) c= 5.25 
5:3 

Your payroll situation now looks like this: 
7:3 

EMPLOYEE HOURLY RATE YEARLY SALARY 
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Example ^ 

Displays the exact hexadecimal contents of a real variable, 
define local 

float, 8, real $$ a real variable 

5 define end 
* 

calc float <= 71 $$ the value of pi 

at 5:3 

write % looks like this in "hex". 
10 at 6:3 

showh float 

showt 

Displays a numeric variable or expression in tabular format. 

showt variable [ , field [ , right ]] 

15 write « showt 1 1, variable [ , field [ , right ]] » 

field total size of display field including leading spaces, digits, and any decimal point 

right number of digits to right of decimal point 

Description 

Displays the value of a numeric variable or expression in a tabular right-justified format by 
20 inserting leading spaces and trailing zeroes as needed to fill the desired field. 

After showt, the current screen location is updated to the character position following the 
' last character displayed . 
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long 20 ^ 

arrow 4 : 3 

storea stuname, zcount 
ok 

endarrow 
at 8:3 

write Thank you, $$$ keep the trailing space 
showa stuname, zcount 

write . $$ put the period on the end 

Example 2 

Displays the name of the current lesson and unit in the upper left comer; 

at 1:1 

write « a,zlesson »:« a,zunit » 

showh 

15 Displays data in hexadecimal notation. 

showh buffer [ , length ] 

write « showh 1 h , buflfer [ , length ] » 

Description 

Displays data in hexadecimal form for length digits. Il length is omitted, enough digits are 
20 used to display the entire defined length of the variable. Each byte of a variable shows as two 
hexadecimal digits. Any length variable can be displayed. 

After a showh, the current screen location is updated to the character position following 
the last character displayed. 
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1 
* 

at 1:65 

write Page « show, page » of 50. 

5 showa 

Displays text stored in a variable. 

showa buffer [ ,length ] 

write «showa | a, buffer [ Iength]» 

Description 

1 0 Displays the contents of a variable buffer as alphanumeric characters for length 

characters. If length is omitted, the defined length of the buffer is used. The contents of any 
numeric variable can be shown, even if it contains non-numeric information. 

After a showa, the current screen location is updated to the character position following 
the last character displayed. Any changes to plotting parameters resulting from escape code 
1 5 sequences in the displayed text remain in effect after the showa. 
Examples 
Example 1 

The user's name is stored in stuname and then displayed using showa: 

define local 

20 stuname, 20 $$ user name 

define end 
* 

at 3:3 

write Please enter your name. 
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updated to the character position following the last character displayed (without leading blaftks or 
trailing zeroes). 

The number of digits to the left of the decimal point is the value of field minus the value 
of right minus 1 

show displays special symbols to indicate the following error conditions: 
****** The number to display does not fit in the specified field. 
?????? The number is invalid. This is usually the result of an illegal floating point 
operation. 

If the optional tags are omitted the following default values are used: 



IF the variable is 


Then default field 
and right are* 


1 -4 byte integer 


20,0 


8 byte interger and reals 


24,3 



10 Examples 
Example 1 

Displays 10 quiz scores. 

at 3:5 

write Here are your last 10 quiz scores: 
15 loop index <= 1, 10 

at index+5:10 
show quizscor (index) 

endloop 

Example 2 

20 Through use of an embedded show command in a write statement, a pagination title is put 

at the top of the display. 
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calc 


array (2) 


• 


calc 


array (3) 


• 


calc 


array (4) 


elseif 


flag 


= 0 


• 


calc 


array (1) 




calc 


array (2) 




calc 


array (3) 




calc 


array ( 4 ) 


elsei£ 


flag 


= 1 


elseif 


flag 


> 2 




calc 


array (1) 




calc 


array (2) 




calc 


array (4) 



c= 2 

c: 3 

C= 4 

c= 4 

c= 3 

c= 2 

c= 1 



$$ skipped selectic 



1 
2 
8 



endif 



Note that in the last list assignment, array(3) is skipped. 



show 



Displays variables or numeric expressions. 



show 
write 
20 field 
right 



expression [ , field [ , right ] ] 

«show 1 s , expression [ , field [ , right ] ]» 

maximum number of digits to display, including any decimal point 

number of digits to display to the right of the decimal point 



Description 

Displays the value of a numeric variable or expression. Optional tags control the format of 
the numeric display. Values are displayed left-justified in the field and the screen location is 
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setc 



10 



Selectively sets variables to a list of values. 

setc SELECTOR ; variable value/s; value/s; . . . 

variable starting variable to assign list of values 

Description 

The selective form of set. Based on the value of the selector, setc selects one of the lists 
of values in the tag and assigns those values to consecutive variables. 

Each list of values must be separated with a semicolon (;). Values within a list must be 
separated with a comma (,)• A null value is used to skip an assignment. The tag of setc may be 
continued in the tag field of subsequent lines. 

The starting variable need not be an array; consecutive following bytes of variable space 
are assigned based on the length and the type of the initial variable. 
Example 

Selectively assign a series of values to an array based on flag. 

define local 
array (10) , 4 
flag, 1 
define end 



* 



setc 



flag, array(l) c= 1,2,3,4; 



4,3,2,1;;1,2, ,8 



The setc command above is equivalent to the following commands: 



if 



flag < 0 



calc 



array ( 1 ) 



<:= 1 
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The arithmetic function bit (value,bit) is used to "read" set bits while bitcnt (valuej'Bits) 
gives the count of bits set in a variable. 
Example 

One-bit flags in the 4-byte variable correct are used to keep track of the judgement for the 
5 25 questions given a student, index contains the current question number. The questions are in 
the array probf ) and the answers are in the array aus\s^( ), After the exam is completed, the bitcnt 
function is used to show the number of correct answers. 

* loop through all 25 questions, show the question, get the 

* answer, and set the flag appropriately 
10 loop index c= 1, 25 

at 5:3 

showa prob (index) $$ display the question 

arrow 20:3 

answer «showa, answ(index)» 

15 . . setbit correct, index, 1 $$ ok 

no 

setbit correct, index, 0 $$ wrong 

judge quit $$ exit the arrow 

endarrow 

20 , erase $$ clear screen for next question 

endloop 
* 

at 25:3 

write The number correct is « s , bitcnt (correct , 25) ». 
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define local ^ 
array (4) , 2 
define end 

set array (1) c= 15, 96, , score*100 

5 or 

set array (1) <= 15 , $$ continued across multiple lines 

score*100 

The set commands above are equivalent to the following calc commands: 

10 calc array (1) <= 15 

calc array (2) c= 96 

calc array(4) c= score*100 

setbit 

Sets a bit in a variable. 

15 setbit variable,bit,value 

variable variable containing the bit to set 
bit bit number to set 

value value for bit (0 or 1) 

Description 

20 Sets a single bit in a variable. With this command, a single variable can be used for a 

number of one-bit flags, making more efficient use of variable space. 

Bit 1 is the left-most (highest-order) bit. A bit number can be specified that crosses 
variable boundaries. If the value to set the bit to is other than zero or one, the right-most bit of 
the value is used. 
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seed save $$ save the seed 

loop index <= 1, 100 

dot index, randi(lOO) 

5 endloop 
pause 

mode erase 

seed save; set $$ restore the saved seed 

loop index <:= 1, 100 

10 set 

Assigns a series of values to consecutive variables. 

set variable c= value 1, value2, ... 

variable starting variable for assignments 

Description 

15 Assigns a list of values to consecutive memory locations, starting at the location of the 

specified variable. The first value to the right of the assignment arrow is assigned to variable. 
After that, consecutive memory locations of the same size and type as variable are assigned the 
remaining values in the tag, regardless of how subsequent variables may be defined. The variable 
given in set is often the first element of an array, but it may be any variable that is valid with calc. 
20 The tags of set may be continued in the tag field of subsequent lines. 
A null "value" can be used to skip an assignment. 
Example 

Assigns a series of values to an array. Note that array(3) is not assigned and retains its 
original value. 
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zmaxpage Maximum number of pages available 

seed 

Obtains or sets the random number seed, 
seed variable4 [; set ] 

5 Description 

Used in the calculation of random numbers. Each time a new random number is 
generated, the system sets the seed to a new value. The random number seed is used by the perm 
conamand and the randi and randf functions 

The current seed is obtained by using a 4-byte integer variable as the single argument to 
10 the seed command. The seed is set by specifying a 4-byte integer value (0 to 4,294,967,295) and 
using the set keyword. The system initializes the seed to the arbitrary value of zclock at start-up. 

The seed command is normally used for repeatable random number sequences: the same 
random number sequence can be generated again by saving the initial seed and restoring it later. 
For example, if two permutation lists are generated starting from the same seed value, the lists 
15 will be identical. 
Example 

A scatter-graph of 100 random dots is first placed on the screen then erased after a pause. 
The seed is saved before the first generation of random dots then restored before the second 
"erase" generation of the same identical dots. 

20 define local 
'save I 4 , integer 
index , 2 
define end 
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2 


80 X 25; text' mono co"a text hieh mono ^ 


3 


80 X 25' text* 16 color c^^a text hieh color 


4 


320 X 200' sraohics' 4 color csa CTranhic<> medium color 


5 


320 X 200* f^ranhics' mono ccra oranhic; medium mono 


6 


640 X 200' f^ranhics' mono ccra oranhic<; hicrh 


7 


80 X 25* text Con MDAI ccra twt 


13 


320 X 200' cxranhic?* 16 color eaa oranhir^: !nu/ 


14 


640 X 200* oranhics' 16 color poa oranhirQ mf*riinm 


16 


640 X 350' c^ranhics' 16 color f*o-a oranhirQ hioh 


17 


640 X 480* cranhics' 2 color mraa oranhirc hioh 


18 


640 X 480' Pranhics* 16 color vaa aranhirc mpHinm 


19 


320 X 200' sranhics* 256 color mrpa crranhir^ mpHiiim 


106* 


800 X 600; graphics; 16 color vga,graphics,high 


107* 


800 X 600; graphics; 256 color evga,graphics,high 


108* 


1024x 768; graphics: 16 color V2a,graphics,altl 


109* 


1024x 768; graphics; 256 color evga.2raphics,altl 


113* 


1280x1024: graphics; 16 color vga,araphics,alt2 


114* 


1280x1024; graphics; 256 color ev2a,2raphics,alt2 


*VESA-compatible display adapters only 


zscreenh Display driver file (.DIS file) in use (adjusted for the display hardware actually 




detected: e.g., if EVGA.DIS detected VGA hardware, zscreenh will be 10) 


0 


cga 


2 


Hercules 


3 


ega 


9 


att 


10 


vga 


11 


mega 


14 


< 

evga 


zinaxcol Maximum number of colors available for current screen type 



zpalincr Minimum change in RGB value required to have an effect on displayed color (see 
zintincr) 



zintincr Minimum change in intensity value required to have an effect on displayed color 
(see zpalincr) 
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zscreent 


Screen type selected 




0 


cga 




2 


hercules 




3 


ega 




9 


att 




10 


vga 




11 


mega 




14 


evga 




zscreenm 


Screen addressing mode 




0 


graphics 




1 


text 




zscreenr 


Screen resolution 




0 


low 




1 


medium 




2 


high 




3 


alti 




4 


alt2 




S 


alt3 




zscreenc 


Screen chrome 




0 


color 




1 


mono 




zscreen 


Screen type as reported by BIOS 




Value 


Meaning Screen Command 




0 


40 X 25; text; mono cga,text medium, mono 




1 


40 X 25; text; 16 color c^a,text,medium,color 
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mcea, hieh. color 


360x480 


256 


262.144 


30:45 


8x16 


VS 


vea. medium 


640x480 


16 


262.144 


30 80 


8x16 


VS 


Enhanced VGA'" • 


vea. hich 


800x600 


16 


262.144 


33 88 


9x18 


S 


V2a. alil 


1024x768 


16 


26:. 144 


38 lo: 


10x20 


s 


vea. alt2 


1280x1024 


16 


262.144 


42:106 


12x24 


s 


evea. low 


640x400 


256 


262.144 


25:80 


8x16 


s 


evea, medium 


640x480 


256 


262.144 


30:80 


8x16 


s 


evea. hieh 


800x600 


256 


262.144 


33:88 


9x18 


s 


evea, altl 


1024x768 


256 


262,144 


38:102 


10x20 


s 


evea. alt2 


1280x1024 


256 


262.144 


42:106 


12x24 


s 



when using VCA.DIS or EVGA.DIS ihe number of possible colors is 262.144 



** display drivers supponing each screen are denoted by the following letters: 
C CGA.DIS 
E EGA.DIS 
5 V VGA.DIS 

S EVGA.DIS 

•••most Super VGA cards supponed, either directly or through VESA standard 
System Variables 
zreturn 

10 The screen command sets zreturn to the following values. 

-2 ok, screen not changed; the requested screen already in effect 

-1 ok, screen changed (not changed for screen test form) 

0 Invalid screen for display driver file 

1 Display adapter does not support requested screen 

15 When a screen command executes successfully, the following set of system variables are 

" reset They are not altered for the screen test form. 



SUBSTITUTE SHEET (RULE 25) 



<W0 9907007A2 I > 



wo 99/07007 



PCT/US98/15627 



359 



Examples 
Example I 

Selects the 640 x 480 x 16 color (vga,medium,graphics,color) screen, if the screen is 
not possible, a message is given before a branch exits the user back to the calling system. 

5 screen vga 

if not (zreturn) $$ see if can't set screen 

write Warning. 

VGA Screen Type not available. 

pause 

10 . jump =exit $$ exit to router or DOS 

endif 

Example 2 

Tests whether the 1280 x 1024 x 256 color screen is available. If so, the high resolution 
version of a chemistry lesson is used. If not, the lower resolution version of the lesson is used. 

15 screen test, evga, alt2 

if zreturn $$ see if true(-l) 

jump chemHigh, start $$ use high resolution version 

else 

jMStp cheinLow, Start $$ use lower resolution version 

20 endif 

Screen Types and Display Drivers 



Screen 


Pixels 


Palette 


Colors 


Chars 


CharSize 


DisplavDrivers 


raM Standard 


cea, medium 


320x200 


4 


16 


20:40 


8x10 


CEVS 


cga. hish 


640x200 


2 


16 


20:80 


8x10 


CEVS 


. eea, low 


320x200 


16 


16* 


„. 20:40 


8x10 


EVS 


e^a, medium 


640x200 


16 


16* 


20:80 


8x10 


EVS 


eca, hish 


640x350 


16 


64* 


25:80 


8x14 


EVS 


mcea, medium 


320x200 


256 


262.144 


20:40 


8x10 


VS 


mcea, hieh 


640x480 


2 


262.144 


30:80 


8x16 


VS 
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